dfhack/README

Introduction
------------
DFHack is a Dwarf Fortress memory access library and a set of basic tools using this library.
The library is a work in progress, so things might change as more tools are written for it.

It is an attempt to unite the various ways tools access DF memory and allow for easier development
of new tools.

Getting DFHack
----------------
You can get the code at DFHack's sourceforge site:
  https://sourceforge.net/projects/dfhack/

* subversion access: 
  svn co https://dfhack.svn.sourceforge.net/svnroot/dfhack/trunk dfhack 

Compatibility
-------------
DFHack works on Windows XP, Vista, 7 or any modern Linux distribution.

Windows 2000 is currently *not supported* due to missing OS functionality. If you know how
to easily suspend processes, you can fix it :)

OSX is also not supported due to lack of developers with a Mac.

Currently supported Dwarf Fortress versions:
* Windows
  40d
  40d9 - 40d16

* Linux
  40d9 - 40d16

Using the library
-----------------
The library is compilable under Linux with GCC and under Windows with MinGW32 and MSVC compilers.
It is using the cmake build system. See COMPILE for details.

DFHack is using the zlib/libpng license. This makes it easy to link to it, use it in-source
or add your own extensions. Contributing back to the dfhack repository is welcome and the right
thing to do :)

At the time of writing there's no API reference or documentation. The code does have a lot
of comments though.

Using DFHack Tools
------------------
The project comes with a special extra library you should add to your DF installation.
It's used to boost the transfer speed between DF and DFHack, and provide data consistency
and synchronization. DFHack will work without the library, but at suboptimal speeds
and the consistency of data written back to DF is questionable.

!!!!Please not that on Windows this currently only works with DF 40d15 and 40d16!!!!
On Linux, it works with the whole range of supported DF versions.

 ** Installing on Windows
 - Open your DF folder, locate SDL.dll and rename it to SDLreal.dll (making a backup of it is a good idea)
 - Copy the DFHack SDL.dll into your DF folder.
 - Restart DF if it is already running

 ** Unistalling on Windows
 - Open your DF folder, locate SDL.dll and delete it
 - Rename SDLreal.dll to SDl.dll
 - Restart DF if it is running


 ** Installing on Linux
 - Open your DF folder and the libs folder within it
 - copy DFHack libdfconnect.so to the libs folder
 - copy the df startup script, name it dfhacked
 - open the new dfhacked startup script and add this line:
     export LD_PRELOAD="./libs/libdfconnect.so" # Hack DF!
   just before the line that launches DF

   Here's an example how the file can look after the change:
#!/bin/sh
DF_DIR=$(dirname "$0")
cd "${DF_DIR}"
export SDL_DISABLE_LOCK_KEYS=1 # Work around for bug in Debian/Ubuntu SDL patch.
#export SDL_VIDEO_CENTERED=1 # Centre the screen.  Messes up resizing.
ldd dwarfort.exe | grep SDL_image | grep -qv "not found$"
if [ $? -eq 0 ]; then
 mkdir unused_libs
 mv libs/libSDL* unused_libs/
fi
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:"./libs" # Update library search path.
export LD_PRELOAD="./libs/libdfconnect.so" # Hack DF!
./dwarfort.exe $* # Go, go, go! :)

 - Use this new startup script to start DF

 ** Uninstalling on Linux
 - Open your DF and DF/libs folders
 - Delete libdfconnect.so and the dfhacked startup script
 - Go back to using the df startup script

Tools
-----
All the DFHack tools are terminal programs. This might seem strange to Windows users,
but these are meant mostly as examples for developers. Still, they can be useful and
are cross-platform just like the library itself.

If the tool writes back to DF's memory, make sure you are using the shared memory interface
mentioned in the previous section!

* expbench   - just exports the map 1000 times over. Meant to test how fast the
               DFHack<->DF interface is. This can take 3-30+ seconds, depending on
               your system and the size of the map.

* reveal     - plain old reveal tool. Demonstrates writing map data back to DF.

* prospector - scans the map for minerals. by default it only scans only visible veins.
               You can make it show hidden things with '-a' and base rock and soil layers
               with '-b'. These can be combined ('-ab')

* cleanmap   - cleans mud, vomit, snow and all kinds of bloody mess from the map. It will
               clean your irrigated farms too, so consider yourself warned.

* dfattachtest - Benchmark for the Attach, Detach, Suspend and Resume functions

* dfbuildingsdump - exports some basic data about buildings of a given type on the game map

* dfcreaturedump - exports some basic data about all the dwarves

* dfcustomCreatureNameProf - allws you to change nicknames and custom professions of your dwarves

* dfincremental - incremental search utility - linux only right now

* dfitemdump - lists items under the current DF cursor (40d16 only)

* dfmaterialtest - tries to load all the material types from DF, shows the first entry of each type

* dfposition - shows you the current view coordinates and window size in tiles
               (may not be implemented for older DF versions)

* dfsuspend - tests the behavior of Suspend and Resume functions

Memory offset definitions
-------------------------
The file with memory offset definitions used by dfhack can be found in the output folder. 
It uses XML as the base format.

It allows entry versioning and basing newer entries on older ones. These newer versions
only have to specify the values that are different or a single 'rebase' value that is then
used as an offset for all the addresses or object identifiers.

This makes it possible to track the small d## releases pretty quickly.

~ EOF ~