MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

develop
lethosor 2015-11-07 15:50:11 -05:00
parent 3ae0b17031 6dacbe3d9f
commit e176c3ea05
49 changed files with 1544 additions and 1390 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
Unescape Escape View File

@ -18,7 +18,7 @@ script:
- python travis/lint.py - python travis/lint.py
- python travis/script-in-readme.py - python travis/script-in-readme.py
- python travis/script-syntax.py --ext=lua --cmd="luac5.2 -p" - 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 - mkdir build-travis
- cd build-travis - cd build-travis
- cmake .. && make -j3 - cmake .. && make -j3

2
CMakeLists.txt
Unescape Escape View File

@ -214,7 +214,7 @@ if (BUILD_DOCS)
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb" "${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(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo")
set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE)

376
LICENSE.rst
Unescape Escape View File

@ -4,14 +4,53 @@
Licenses Licenses
######## ########
DFHack is distributed under a range of permissive and weakly copyleft licenses. DFHack is distributed under the Zlib license, with some MIT-
and BSD-licensed components. These licenses protect your right
The core uses the ZLib license; the others are described below. to use DFhack for any purpose, distribute copies, and so on.
License of DFHack The core, plugins, scripts, and other DFHack code all use the
================= ZLib license unless noted otherwise. By contributing to DFHack,
https://github.com/peterix/dfhack authors release the contributed work under this license.
Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com)
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 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 1. The origin of this software must not be misrepresented; you must
not claim that you wrote the original software. If you use this not claim that you wrote the original software. If you use this
software in a product, an acknowledgment in the product documentation software in a product, an acknowledgment in the product
would be appreciated but is not required. documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and 2. Altered source versions must be plainly marked as such, and
must not be misrepresented as being the original software. 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 3. This notice may not be removed or altered from any source
distribution. distribution.
clsocket license MIT 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
=========== ===========
See https://en.wikipedia.org/wiki/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
=================================================
:: ::
Copyright (C) 2006 Toni Ronkko
Permission is hereby granted, free of charge, to any person obtaining Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including "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 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL TONI RONKKO BE LIABLE FOR ANY CLAIM, DAMAGES OR IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
OTHER DEALINGS IN THE SOFTWARE. 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 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 Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are modification, are permitted provided that the following conditions are
met: 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. notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright 2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the notice, this list of conditions and the following disclaimer in
documentation and/or other materials provided with the distribution. the documentation and/or other materials provided with the
distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT "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 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
``linenoise`` adds no further clauses.
UTF-8 Decoder ``protobuf`` adds the following clause::
=============
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.
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 ``clsocket`` adds the following clauses::
========
Copyright 2010-2014 Jeffrey Friedl, http://regex.info/blog/
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: 4. The name "CarrierLabs" must not be used to endorse or promote
http://creativecommons.org/licenses/by/3.0/deed.en_US products derived from this software without prior written
permission. For written permission, please contact
mark@carrierlabs.com

24
NEWS.rst
Unescape Escape View File

@ -105,7 +105,7 @@ Fixes
- help: now recognizes built-in commands, like "help" - help: now recognizes built-in commands, like "help"
- `manipulator`: fixed crash when selecting custom professions when none are found - `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 - `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 - `stockpiles`: now checks/sanitizes filenames when saving
- `stocks`: fixed a crash when right-clicking - `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 - `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 - `prospect`: works from within command-prompt
- `quicksave`: Restricted to fortress mode - `quicksave`: Restricted to fortress mode
- `remotefortressreader`: Exposes more information - `remotefortressreader`: Exposes more information
- `search`: - `search-plugin`:
- Supports noble suggestion screen (e.g. suggesting a baron) - Supports noble suggestion screen (e.g. suggesting a baron)
- Supports fortress mode loo[k] menu - Supports fortress mode loo[k] menu
@ -201,8 +201,8 @@ Lua
New Internal Commands New Internal Commands
--------------------- ---------------------
- `hide, show`: hide and show the console on Windows - `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) - `sc-script`: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts)
New Plugins New Plugins
----------- -----------
@ -474,8 +474,8 @@ Misc Improvements
- `EventManager`: deals with frame_counter getting reset properly now. - `EventManager`: deals with frame_counter getting reset properly now.
- `modtools/item-trigger`: fixed equip/unequip bug and corrected minor documentation error - `modtools/item-trigger`: fixed equip/unequip bug and corrected minor documentation error
- `teleport`: Updated with proper argument handling and proper unit-at-destination handling. - `teleport`: Updated with proper argument handling and proper unit-at-destination handling.
- `autotrade <Stockpile automation>`: Removed the newly obsolete :guilabel:`Mark all` functionality. - `autotrade`: Removed the newly obsolete :guilabel:`Mark all` functionality.
- `search`: Adapts to the new trade screen column width - `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 - `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 duplicate load/unload events when unloading a world
- Stopped ``-e`` from being echoed when DFHack quits on Linux - Stopped ``-e`` from being echoed when DFHack quits on Linux
- `automelt <Stockpile automation>`: now uses a faster method to locate items - `automelt`: now uses a faster method to locate items
- `autotrade <Stockpile automation>`: "Mark all" no longer double-marks bin contents - `autotrade`: "Mark all" no longer double-marks bin contents
- `drain-aquifer`: new script replaces the buggy plugin - `drain-aquifer`: new script replaces the buggy plugin
- `embark-tools`: no longer conflicts with keys on the notes screen - `embark-tools`: no longer conflicts with keys on the notes screen
- `fastdwarf`: Fixed problems with combat/attacks - `fastdwarf`: Fixed problems with combat/attacks
@ -541,18 +541,18 @@ Internals
New Plugins New Plugins
----------- -----------
- `hotkeys`: Shows ingame viewscreen with all dfhack keybindings active in current mode. - `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 Fixes
----- -----
- possible crash fixed for `gui/hack-wish` - 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 - `workflow`: job_material_category -> dfhack_material_category
Misc Improvements Misc Improvements
----------------- -----------------
- now you can use ``@`` to print things in interactive Lua with subtley different semantics - 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+ - updated `exportlegends` to work with new maps, dfhack 40.11 r1+
@ -565,7 +565,7 @@ Internals
Fixes Fixes
----- -----
- `3dveins`: should no longer hang/crash on specific maps - `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 - `deathcause`: updated
- `gui/hack-wish`: should work now - `gui/hack-wish`: should work now
- `reveal`: no longer allocates data for nonexistent map blocks - `reveal`: no longer allocates data for nonexistent map blocks

6
README.html
Unescape Escape View File

@ -4,13 +4,13 @@
<html lang="en-US"> <html lang="en-US">
<head> <head>
<meta charset="UTF-8"> <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"> <script type="text/javascript">
window.location.href = "./docs/html/index.html" window.location.href = "./docs/html/docs/index.html"
</script> </script>
<title>Page Redirection</title> <title>Page Redirection</title>
</head> </head>
<body> <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> </body>
</html> </html>

54
conf.py
Unescape Escape View File

@ -1,8 +1,7 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# #
# DFHack documentation build configuration file, created by # DFHack documentation build configuration file
# sphinx-quickstart on Tue Sep 22 17:34:54 2015.
# #
# This file is execfile()d with the current directory set to its # This file is execfile()d with the current directory set to its
# containing dir. # containing dir.
@ -18,25 +17,24 @@ from io import open
import os import os
import shlex import shlex
import sys import sys
import shutil
# -- Autodoc for DFhack scripts -------------------------------------------
def doc_dir(dirname, files): def doc_dir(dirname, files):
"""Yield (command, includepath) for each script in the directory.""" """Yield (command, includepath) for each script in the directory."""
sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '') sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '')
for f in files: for f in files:
if f[-3:] not in {'lua', '.rb'}: if f[-3:] not in ('lua', '.rb'):
continue continue
with open(os.path.join(dirname, f), 'r', encoding='utf8') as fstream: with open(os.path.join(dirname, f), 'r', encoding='utf8') as fstream:
text = [l.rstrip() for l in fstream.readlines() if l.strip()] text = [l.rstrip() for l in fstream.readlines() if l.strip()]
command = None command = None
for line in text: for line in text:
if line == len(line) * '=': if command and line == len(line) * '=':
if command is not None:
yield command, sdir + '/' + f yield command, sdir + '/' + f
break break
command = line command = line
# later, print an error for missing docs here
def document_scripts(): def document_scripts():
@ -89,11 +87,6 @@ def document_scripts():
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 ------------------------------------------------ # -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here. # If your documentation needs a minimal Sphinx version, state it here.
@ -113,24 +106,22 @@ extlinks = {
'Bay12 forums thread '), 'Bay12 forums thread '),
'dffd': ('http://dffd.bay12games.com/file.php?id=%s', 'DFFD file '), 'dffd': ('http://dffd.bay12games.com/file.php?id=%s', 'DFFD file '),
'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s', '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. # Add any paths that contain templates here, relative to this directory.
templates_path = [] templates_path = []
# The suffix(es) of source filenames. # The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string: # You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst' source_suffix = '.rst'
# The encoding of source files. # The encoding of source files.
#source_encoding = 'utf-8-sig' #source_encoding = 'utf-8-sig'
# The master toctree document. # The master toctree document.
master_doc = 'index' master_doc = 'docs/index'
# General information about the project. # General information about the project.
project = 'DFHack' project = 'DFHack'
@ -145,7 +136,7 @@ def get_version():
"""Return the DFHack version string, from CMakeLists.txt""" """Return the DFHack version string, from CMakeLists.txt"""
version = release = '' version = release = ''
try: try:
with open('../CMakeLists.txt') as f: with open('CMakeLists.txt') as f:
for s in f.readlines(): for s in f.readlines():
if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'): if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'):
version = s.upper().replace('SET(DF_VERSION "', '') version = s.upper().replace('SET(DF_VERSION "', '')
@ -179,19 +170,9 @@ exclude_patterns = ['docs/_build/*', 'depends/*', 'scripts/3rdparty/*', 'build*'
# documents. # documents.
default_role = 'ref' 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. # The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx' 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. # If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False 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, # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format. # 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 # If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities. # typographically correct entities.
@ -255,9 +236,9 @@ html_static_path = ['docs/styles']
html_sidebars = { html_sidebars = {
'**': [ '**': [
'about.html', 'about.html',
'localtoc.html',
'relations.html', 'relations.html',
'searchbox.html', 'searchbox.html',
'localtoc.html',
] ]
} }
@ -288,19 +269,6 @@ html_use_index = False
# base URL from which the finished HTML is served. # base URL from which the finished HTML is served.
#html_use_opensearch = '' #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. # Output file base name for HTML help builder.
htmlhelp_basename = 'DFHackdoc' htmlhelp_basename = 'DFHackdoc'

9
docs/Authors.rst
Unescape Escape View File

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

13
docs/Binpatches.rst
Unescape Escape View File

@ -32,8 +32,7 @@ decent skill in `memory research <contributing-memory-research>`.
* See `this commit <https://github.com/DFHack/dfhack/commit/8a9e3d1a728>`_, * See `this commit <https://github.com/DFHack/dfhack/commit/8a9e3d1a728>`_,
when the 0.34.11 patches were discarded, for example patches. when the 0.34.11 patches were discarded, for example patches.
* `Issue #546 <https://github.com/DFHack/dfhack/issues/546>`_ is about the * :issue:`546` is about the future of the binpatches, and may be useful reading.
future of the binpatches, and may be useful reading.
If you want to write a patch, the armory patches discussed here and documented If you want to write a patch, the armory patches discussed here and documented
below would probably be the best place to start. 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 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 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 Patching on disk
@ -152,8 +151,8 @@ these rules is intended by Toady; the rest are invented by this plugin.
gui/assign-rack gui/assign-rack
--------------- ---------------
Bind to a key (the example config uses P), and activate when viewing a weapon Bind to a key (the example config uses :kbd:`P`), and activate when viewing a weapon
rack in the ``q`` mode. rack in the :kbd:`q` mode.
.. image:: images/assign-rack.png .. 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 * Even if assigned by the script, **the game will unassign the racks again
without a binary patch**. This patch is called ``weaponrack-unassign``, 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. and has not been updated since 0.34.11. See :bug:`1445` 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, * Haulers still take equipment stored in the armory away to the stockpiles,
unless `fix-armory` is used. unless `fix-armory` is used.

184
docs/Compile.rst
Unescape Escape View File

@ -2,28 +2,20 @@
Compiling DFHack Compiling DFHack
################ ################
.. important:: You don't need to compile DFHack unless you're developing plugins or working on the core.
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. For users, modders, and authors of scripts it's better to download
and `install the latest release instead <installing>`.
.. contents:: .. contents::
:depth: 2 :depth: 2
===================
How to get the code How to get the code
=================== ===================
DFHack doesn't have any kind of system of code snapshots in place, so you will have to 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. get code from the github repository using git. How to get git is described under
The code resides at https://github.com/DFHack/dfhack the instructions for each platform.
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
To get the code:: 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 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. ``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 If you want to get involved with the development, create an account on
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
Github, make a clone there and then use that as your remote repository instead. 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, We'd love that; join us on IRC (#dfhack channel on freenode) if you need help.
join us on IRC (#dfhack channel on freenode).
===========
Build types Build types
=========== ===========
``cmake`` allows you to pick a build type by changing this ``cmake`` allows you to pick a build type by changing the ``CMAKE_BUILD_TYPE`` variable::
variable: ``CMAKE_BUILD_TYPE`` ::
cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE 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 Valid and useful build types include 'Release', 'Debug' and
'RelWithDebInfo'. 'Debug' is not available on Windows. 'RelWithDebInfo'. 'Debug' is not available on Windows.
=====
Linux Linux
===== =====
On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD. On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD.
Dependencies Dependencies
============ ------------
DFHack is meant to be installed into an existing DF folder, so get one ready. 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 We assume that any Linux platform will have ``git`` available.
a 64-bit distribution like Arch, you'll need the multilib development tools and libraries.
Alternatively, you might be able to use ``lxc`` to To build DFHack you need a 32-bit version of GCC. On 64-bit distributions
`create a virtual 32-bit environment <http://www.bay12forums.com/smf/index.php?topic=139553.msg5435310#msg5435310>`_. (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 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. ``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 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 You should be able to find them in your distro repositories.
``perl-xml-libxml`` and ``perl-xml-libxslt``) or through ``cpan``.
* 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. 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 Build
===== -----
Building is fairly straightforward. Enter the ``build`` folder (or create an 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:: 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 make install
This will show a curses-based interface that lets you set all of the This will show a curses-based interface that lets you set all of the
extra options. extra options. You can also use a cmake-friendly IDE like KDevelop 4
or the cmake-gui program.
You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui
program.
Fixing the libstdc++ version bug
================================
Incompatible libstdc++
~~~~~~~~~~~~~~~~~~~~~~
When compiling dfhack yourself, it builds against your system libc. When compiling dfhack yourself, it builds against your system libc.
When Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which 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. 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 ./libs/Dwarf_Fortress: /pathToDF/libs/libstdc++.so.6: version
`GLIBCXX_3.4.15' not found (required by ./hack/libdfhack.so) `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 fix this, you can compile DFHack with GCC 4.5 - or simply remove the
to your system lib and everything will work fine:: libstdc++ shipped with DF, and it will fall back to your system lib::
cd /path/to/DF/ cd /path/to/DF/
rm libs/libstdc++.so.6 rm libs/libstdc++.so.6
Alternatively, this issue can be avoided by compiling DFHack with GCC 4.5.
========
Mac OS X Mac OS X
======== ========
DFHack functions similarly on OS X and Linux, and the majority of the DFHack functions similarly on OS X and Linux, and the majority of the
information above regarding the build process (cmake and make) applies here information above regarding the build process (cmake and make) applies here
as well. as well.
* If you are building on 10.6, please read the subsection below titled "Snow Leopard Changes" FIRST. If you have issues building on OS X Yosemite (or above), try definining the
* If you are building on 10.10+, read the "Yosemite Changes" subsection before building. following environment variable::
export MACOSX_DEPLOYMENT_TARGET=10.9
1. Download and unpack a copy of the latest DF #. Download and unpack a copy of the latest DF
2. Install Xcode from Mac App Store #. Install Xcode from Mac App Store
3. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools. #. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools.
4. Install dependencies #. Install dependencies
Option 1: Using Homebrew: Using `Homebrew <http://brew.sh/>`_::
* `Install Homebrew <http://brew.sh/>`_ and run: brew tap homebrew/versions
* ``brew tap homebrew/versions`` brew install git
* ``brew install git`` brew install cmake
* ``brew install cmake`` brew install gcc45
* ``brew install gcc45``
Option 2: Using MacPorts: Using `MacPorts <https://www.macports.org>`_::
* `Install MacPorts <http://www.macports.org/>`_ sudo port install gcc45 +universal cmake +universal git-core +universal
* Run ``sudo port install gcc45 +universal cmake +universal git-core +universal``
This will take some time—maybe hours, depending on your machine.
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`` 1. ``sudo cpan``
If this is the first time you've run cpan, you will need to go through the setup 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. 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`` 2. ``install XML::LibXML``
3. ``install XML::LibXSLT`` 3. ``install XML::LibXSLT``
6. Get the dfhack source:: #. Get the dfhack source::
git clone --recursive https://github.com/DFHack/dfhack.git git clone --recursive https://github.com/DFHack/dfhack.git
cd dfhack cd dfhack
7. Set environment variables: #. Set environment variables:
Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``):: Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``)::
@ -186,7 +174,7 @@ as well.
export CC=/opt/local/bin/gcc-mp-4.5 export CC=/opt/local/bin/gcc-mp-4.5
export CXX=/opt/local/bin/g++-mp-4.5 export CXX=/opt/local/bin/g++-mp-4.5
8. Build dfhack:: #. Build dfhack::
mkdir build-osx mkdir build-osx
cd build-osx cd build-osx
@ -195,42 +183,24 @@ as well.
make install 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 Windows
======= =======
On Windows, DFHack replaces the SDL library distributed with DF. On Windows, DFHack replaces the SDL library distributed with DF.
Dependencies Dependencies
============ ------------
First, you need ``cmake``. Get the win32 installer version from the official You will need some sort of Windows port of git, or a GUI. Some examples:
site: http://www.cmake.org/cmake/resources/software.html
* `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 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. 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. You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient.
Grab it from Microsoft's site. Grab it from Microsoft's site. You'll also need the Visual Studio 2010 SP1 update.
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. For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT.
`Strawberry Perl <http://strawberryperl.com>`_ works nicely for this. `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. all the required packages.
Build 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): 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). * ``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. * ``gui`` will pop up the cmake gui and let you pick and choose what to build.
* ``minimal`` will create a minimal solution with just the bare necessities - the main library and standard plugins. 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: 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 ``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. * 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 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. 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.

24
docs/Contributing.rst
Unescape Escape View File

@ -11,7 +11,6 @@ Several things should be kept in mind when contributing code to DFHack.
Code Format Code Format
----------- -----------
* Four space indents for C++. Never use tabs for indentation in any language. * Four space indents for C++. Never use tabs for indentation in any language.
* LF (Unix style) line terminators * LF (Unix style) line terminators
* Avoid trailing whitespace * Avoid trailing whitespace
@ -25,14 +24,18 @@ Code Format
How to get new code into DFHack How to get new code into DFHack
------------------------------- -------------------------------
* Submit pull requests to the ``develop`` branch, not the ``master`` branch.
* Submit pull requests to the ``develop`` branch, not the master branch. The master branch always points at the most recent release. (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). * 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 * 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 * Create a GitHub pull request once finished
* Work done against GitHub issues tagged "bug" get priority * Submit ideas and bug reports as :issue:`issues on GitHub <>`.
* Submit ideas and bug reports as issues on GitHub. Posts in the forum thread can easily get missed or forgotten. 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: .. _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. 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. ``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. 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. 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 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:: Input values are specified in angle brackets. Example::
Options: Usage:
:arg1: A simple argument. :arg1: A simple argument.
:arg2 <input>: Does something based on the input value. :arg2 <input>: Does something based on the input value.

499
docs/Core.rst
Unescape Escape View File

@ -1,216 +1,106 @@
.. _dfhack-core:
########### ###########
DFHack Core DFHack Core
########### ###########
.. contents:: DFHack commands can be implemented in three ways, all of which
are used in the same way:
==============
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
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``, :plugins: are stored in ``hack/plugins/`` and must be compiled with the
then remove the other DFHack files same version of DFHack. They are less flexible than scripts,
* On Linux, remove the DFHack files. 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. Built-in Commands
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 The following commands are provided by the 'core' components
they are re-created every time it is loaded. 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/`` .. _cls:
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! cls
============================= ---
First, don't panic :) 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`_, .. _die:
`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 ---
============= Instantly kills DF without saving.
DFHack command syntax consists of a command name, followed by arguments separated
by whitespace. To include whitespace in an argument, quote it in double quotes.
To include a double quote character, use ``\"`` inside double quotes.
If the first non-whitespace character of a line is ``#``, the line is treated
as a comment, i.e. a silent no-op command.
When reading commands from dfhack.init or with the ``script`` command, if the final .. _disable:
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 .. _enable:
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::
:foo a b "c d" e f enable
foo "a b \"c d\" e f" ------
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 enable or disable plugins that support this, use their names as
to retrieve further help without having to look at this document. Alternatively, arguments for the command::
some accept a ``help`` or ``?`` as an option on their command line.
.. 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 .. _fpause:
merely add keybinding hints to existing screens, they use red instead of green for the key.
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, .. _help:
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`` help
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``. 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 Some commands (including many scripts) instead take ``help`` or ``?``
command executed automatically. We recommend modifying or deleting ``dfhack.init-example`` as as an option on their command line - ie ``<cmd> help``.
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. .. _hide:
It will look for them in the main DF directory, and in ``data/save/_____/raw`` and hide
``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame. ----
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, .. _keybinding:
these files may be in any of the above three places. All matching init files will be
executed in alphebetical order.
Setting keybindings keybinding
=================== ----------
To set keybindings, use the built-in ``keybinding`` command. Like any other 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 command it can be used at any time from the console, but bindings are not
in the DFHack init file. 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. 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 ``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 UI state where the binding would be applicable. If called without parameters,
the ``keybinding`` command among other things prints the current context string. the ``keybinding`` command among other things prints the current context string.
Only bindings with a ``context`` tag that either matches the current context fully, 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. 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``, when in context ``foo/bar/baz``, keybindings restricted to any of ``@foo/bar/baz``,
``@foo`` or none. Multiple contexts can be specified by separating them with a ``@foo/bar``, ``@foo`` or none will be active.
pipe (``|``) - for example, ``@foo|bar|baz/foo``.
Hotkeys Multiple contexts can be specified by separating them with a
======= pipe (``|``) - for example, ``@foo|bar|baz/foo`` would match
Opens an in-game screen showing DFHack keybindings that are active in the current context. 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 kill-lua
====================== --------
The ``command-prompt`` plugin adds an in-game DFHack terminal, where you Stops any currently-running Lua scripts. By default, scripts can
can enter other commands. It's default keybinding is Ctrl-Shift-P. 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 load
================ ----
Many plugins can be in a distinct enabled or disabled state. Some of ``load``, ``unload``, and ``reload`` control whether a plugin is loaded
them activate and deactivate automatically depending on the contents into memory - note that plugins are loaded but disabled unless you do
of the world raws. Others store their state in world data. However a something. Usage::
number of them have to be enabled globally, and the init file is the
right place to do it.
Most such plugins or scripts support the built-in ``enable`` and ``disable`` load|unload|reload PLUGIN|(-a|--all)
commands. Calling them at any time without arguments prints a list
of enabled and disabled plugins, and shows whether that can be changed
through the same commands.
To enable or disable plugins that support this, use their names as Allows dealing with plugins individually by name, or all at once.
arguments for the command::
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 Other init files
----------- ----------------
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. * ``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 * non-whitespace characters following the ``:`` are the command name
------- * the remaining part of the line is used verbatim as the first argument
Disables pausing (both manual and automatic) with the exception of pause forced
by 'reveal hell'. This is nice for digging under rivers.

107
docs/Introduction.rst
Unescape Escape View File

@ -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)

1151
docs/Plugins.rst
View File

File diff suppressed because it is too large Load Diff

16
docs/Scripts.rst
Unescape Escape View File

@ -2,20 +2,10 @@
DFHack Scripts DFHack Scripts
############## ##############
Lua or ruby scripts placed in the ``hack/scripts/`` directory are considered for Lua or ruby scripts placed in the :file:`hack/scripts/` directory
execution as if they were native DFHack commands. They are listed at the end are considered for execution as if they were native DFHack commands.
of the ``ls`` command output.
Note: scripts in subdirectories of hack/scripts/ can still be called, but will The following pages document all the scripts in the DFHack standard library.
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.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

35
index.rst → docs/index.rst
Unescape Escape View File

@ -4,8 +4,15 @@ Welcome to DFHack's documentation!
Introduction Introduction
============ ============
DFHack is a Dwarf Fortress memory access library, distributed with scripts DFHack is a Dwarf Fortress memory access library, distributed with
and plugins implementing a wide variety of useful functions and tools. 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 For users, it provides a significant suite of bugfixes and interface
enhancements by default, and more can be enabled. There are also many tools enhancements by default, and more can be enabled. There are also many tools
@ -29,9 +36,10 @@ User Manual
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
docs/Core /docs/Introduction
docs/Plugins /docs/Core
docs/Scripts /docs/Plugins
/docs/Scripts
Other Contents Other Contents
============== ==============
@ -39,9 +47,9 @@ Other Contents
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
docs/Authors /docs/Authors
LICENSE /LICENSE
NEWS /NEWS
For Developers For Developers
============== ==============
@ -49,8 +57,9 @@ For Developers
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
docs/Contributing /docs/Contributing
docs/Compile /docs/Compile
docs/Lua API /docs/Lua API
library/xml/SYNTAX /library/xml/SYNTAX
docs/Binpatches /library/xml/how-to-update
/docs/Binpatches

11
plugins/advtools.cpp
Unescape Escape View File

@ -41,6 +41,17 @@ using df::nemesis_record;
using df::historical_figure; using df::historical_figure;
using namespace DFHack::Translation; 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"); DFHACK_PLUGIN("advtools");
REQUIRE_GLOBAL(world); REQUIRE_GLOBAL(world);

5
plugins/dwarfexport/dwarfexport.cpp
Unescape Escape View File

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

6
plugins/mapexport/mapexport.cpp
Unescape Escape View File

@ -21,6 +21,12 @@ using namespace google::protobuf::io;
using namespace DFHack; using namespace DFHack;
using df::global::world; 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; typedef std::vector<df::plant *> PlantList;

15
plugins/misery.cpp
Unescape Escape View File

@ -14,6 +14,21 @@
using namespace std; using namespace std;
using namespace DFHack; 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("misery");
DFHACK_PLUGIN_IS_ENABLED(is_enabled); DFHACK_PLUGIN_IS_ENABLED(is_enabled);

18
plugins/treefarm.cpp
Unescape Escape View File

@ -20,6 +20,24 @@
//#include "df/world.h" //#include "df/world.h"
using namespace DFHack; 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("treefarm");
DFHACK_PLUGIN_IS_ENABLED(enabled); DFHACK_PLUGIN_IS_ENABLED(enabled);

8
scripts/devel/about.txt
Unescape Escape View File

@ -1,2 +1,6 @@
``devel/*`` scripts are intended for developers, or still substantially unfinished. ``devel/*`` scripts are intended for developer use, but many may
If you don't already know what they do, best to leave them alone. 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.

10
scripts/devel/all-bob.lua
Unescape Escape View File

@ -1,6 +1,14 @@
--all-bob.lua --all-bob.lua
--author expwnent --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 for _,v in ipairs(df.global.world.units.all) do
v.name.first_name = "Bob" v.name.first_name = "Bob"

10
scripts/devel/cmptiles.lua
Unescape Escape View File

@ -1,5 +1,13 @@
-- Lists and/or compares two tiletype material groups. -- 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 nmat1,nmat2=...
local mat1 = df.tiletype_material[nmat1] local mat1 = df.tiletype_material[nmat1]

7
scripts/devel/export-dt-ini.lua
Unescape Escape View File

@ -1,4 +1,11 @@
-- Exports an ini file for Dwarf Therapist. -- 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 utils = require 'utils'
local ms = require 'memscan' local ms = require 'memscan'

38
scripts/devel/find-offsets.lua
Unescape Escape View File

@ -1,19 +1,39 @@
-- Find some offsets for linux. -- Find some offsets for linux.
--[[=begin
local utils = require 'utils' devel/find-offsets
local ms = require 'memscan' ==================
local gui = require 'gui' 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: Arguments:
* global names to force finding them * global names to force finding them
* 'all' to force all globals * ``all`` to force all globals
* 'nofeed' to block automated fake input searches * ``nofeed`` to block automated fake input searches
* 'nozoom' to disable neighboring object heuristics * ``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 local is_known = dfhack.internal.getAddress

28
scripts/devel/inject-raws.lua
Unescape Escape View File

@ -1,14 +1,26 @@
-- Injects new reaction, item and building defs into the world. -- Injects new reaction, item and building defs into the world.
--[[=begin
-- The savegame contains a list of the relevant definition tokens in devel/inject-raws
-- the right order, but all details are read from raws every time. =================
-- This allows just adding stub definitions, and simply saving and WARNING: THIS SCRIPT CAN PERMANENLY DAMAGE YOUR SAVE.
-- reloading the game.
-- Usage example: This script attempts to inject new raw objects into your
--[[ world. If the injected references do not match the actual
devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER 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' local utils = require 'utils'

7
scripts/devel/inspect-screen.lua
Unescape Escape View File

@ -1,4 +1,11 @@
-- Read the tiles from the screen and display info about them. -- 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 utils = require 'utils'
local gui = require 'gui' local gui = require 'gui'

13
scripts/devel/light.lua
Unescape Escape View File

@ -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 gui = require 'gui'
local guidm = require 'gui.dwarfmode' local guidm = require 'gui.dwarfmode'
local render = require 'plugins.rendermax' local render = require 'plugins.rendermax'

10
scripts/devel/list-filters.lua
Unescape Escape View File

@ -1,6 +1,12 @@
-- List input items for the building currently being built. -- List input items for the building currently being built.
-- --[[=begin
-- This is where the filters in lua/dfhack/buildings.lua come from.
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 dumper = require 'dumper'
local utils = require 'utils' local utils = require 'utils'

7
scripts/devel/lsmem.lua
Unescape Escape View File

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

8
scripts/devel/lua-example.lua
Unescape Escape View File

@ -1,4 +1,12 @@
-- Example of a lua script. -- 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 run_count = (run_count or 0) + 1

9
scripts/devel/migrants-now.lua
Unescape Escape View File

@ -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)
})

10
scripts/devel/nuke-items.lua
Unescape Escape View File

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

7
scripts/devel/pop-screen.lua
Unescape Escape View File

@ -1,3 +1,10 @@
-- For killing bugged out gui script screens. -- 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()) dfhack.screen.dismiss(dfhack.gui.getCurViewscreen())

12
scripts/devel/prepare-save.lua
Unescape Escape View File

@ -1,4 +1,16 @@
-- Prepare the current save for use with devel/find-offsets. -- 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' local utils = require 'utils'

9
scripts/devel/print-args.lua
Unescape Escape View File

@ -1,6 +1,13 @@
--print-args.lua --print-args.lua
--author expwnent --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 = {...} local args = {...}
for _,arg in ipairs(args) do for _,arg in ipairs(args) do

9
scripts/devel/print-args2.lua
Unescape Escape View File

@ -1,6 +1,13 @@
--print-args2.lua --print-args2.lua
--author expwnent --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 = {...} local args = {...}
print("print-args") print("print-args")

8
scripts/devel/scanitemother.rb
Unescape Escape View File

@ -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 tg = df.item_find
raise 'select an item' if not tg raise 'select an item' if not tg

22
scripts/devel/spawn-unit-helper.rb
Unescape Escape View File

@ -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 df.world.arena_spawn.creature_cnt[df.world.arena_spawn.race.length-1] = 0
puts <<EOS puts <<EOS
Arena spawn data initialized. =begin
Now enter the 'k' menu, change mode using: devel/spawn-unit-helper
rb_eval df.gametype = :DWARF_ARENA =======================
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: - enter the :kbd:`k` menu and change mode using
rb_eval df.gametype = #{df.gametype.inspect} ``rb_eval df.gametype = :DWARF_ARENA``
To convert spawned creatures to livestock, select each one with the 'v' menu, and enter: - spawn creatures (:kbd:`c` ingame)
rb_eval df.unit_find.civ_id = df.ui.civ_id
- 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 EOS

7
scripts/devel/test-perlin.lua
Unescape Escape View File

@ -1,4 +1,11 @@
-- Generates an image using multiple octaves of perlin noise. -- 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 args = {...}
local rng = dfhack.random.new(3) local rng = dfhack.random.new(3)

7
scripts/devel/unforbidall.rb
Unescape Escape View File

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

7
scripts/devel/unit-path.lua
Unescape Escape View File

@ -1,4 +1,11 @@
-- Show the internal path a unit is currently following. -- 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 utils = require 'utils'
local gui = require 'gui' local gui = require 'gui'

9
scripts/devel/watch-minecarts.lua
Unescape Escape View File

@ -1,4 +1,13 @@
-- Logs minecart coordinates and speeds to console. -- 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 {} last_stats = last_stats or {}

9
scripts/gui/power-meter.lua
Unescape Escape View File

@ -5,6 +5,15 @@ gui/power-meter
=============== ===============
An in-game interface for `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]] =end]]
local utils = require 'utils' local utils = require 'utils'
local gui = require 'gui' local gui = require 'gui'

11
scripts/migrants-now.lua
Unescape Escape View File

@ -1,11 +1,16 @@
-- Force a migrant wave (only works after hardcoded waves) -- Force a migrant wave (only works after hardcoded waves)
--@alias = 'devel/migrants-now'
--[[=begin --[[=begin
migrants-now migrants-now
============ ============
Forces an immediate migrant wave. Only works after migrants have Forces an immediate migrant wave. Only works after migrants have
arrived naturally. Alias for ``devel/migrants-now``; equivalent to arrived naturally. Equivalent to `modtools/force` ``-eventType migrants``
`modtools/force` ``-eventType migrants``
=end]] =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)
})

1
scripts/source.rb
Unescape Escape View File

@ -4,6 +4,7 @@
source source
====== ======
Create an infinite magma or water source or drain on a tile. 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 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. that tile receives or remove 1 new unit of flow based on the configuration.

5
travis/lint.py
Unescape Escape View File

@ -65,8 +65,11 @@ class Linter(object):
class NewlineLinter(Linter): class NewlineLinter(Linter):
msg = 'Contains DOS-style newlines' 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): def check_line(self, line):
return '\r' not in line return self.ignore or '\r' not in line
def fix_line(self, line): def fix_line(self, line):
return line.replace('\r', '') return line.replace('\r', '')

43
travis/script-in-readme.py
Unescape Escape View File

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

28
travis/script-syntax.py
Unescape Escape View File

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