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

Updated README and COMPILE, split tools into tools and examples. 

Tools are now useful, and with a working user interaction where applicable.
Examples are a collection of benchmarks, tests and simple unfinished ideas.
develop
Petr Mrázek 2010-02-16 07:21:38 +01:00
parent 56969fb977
commit 054fec0afc
16 changed files with 190 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CMakeLists.txt
Unescape Escape View File

@ -29,4 +29,5 @@ include_directories (${CMAKE_SOURCE_DIR}/shmserver/)
add_subdirectory (library)
add_subdirectory (tools)
add_subdirectory (examples)
add_subdirectory (shmserver)

64
COMPILE
Unescape Escape View File

@ -4,6 +4,7 @@ Here's how you build dfhack!
First, there is one dependency, regardless of the OS you use:
cmake - it's the build system
Building on Linux:
--------------------
@ -30,8 +31,7 @@ library to $CMAKE_INSTALL_PREFIX/lib
executables to $CMAKE_INSTALL_PREFIX/bin
The Memory.xml file to /usr/share/dfhack
A special library for adding a shared memory interface to DF is also compiled (libdfconnect.so)
It can be put into DF/libs and preloaded using LD_PRELOAD
See the section on the shared memory hook library (SHM).
Building on Windows:
--------------------
@ -51,9 +51,6 @@ You'll have to add C:\MinGW\ to your PATH variable.
cmake .. -G"MinGW Makefiles" -DCMAKE_BUILD_TYPE:string=Release
mingw32-make
A special library for adding a shared memory interface to DF is also compiled (SDL.dll)
You can use it with DF by renaming the original SDL.dll to SDLreal.dll and dropping in the newly compiled library.
* Using MSVC
open up cmd and navigate to the dfhack\build folder, run cmake:
@ -64,22 +61,73 @@ This will generate MSVC solution and project files. Note that: you are working i
Files added to projects will end up there! (and that's wrong). Any changes to the build system should
be done by changing cmake configs and running cmake on them!
A special library for adding a shared memory interface to DF is also compiled (SDL.dll)
You can use it with DF by renaming the original SDL.dll to SDLreal.dll and dropping in the newly compiled library.
* Using some other compiler:
I'm afraid you are on your own. dfhack wasn't tested with any other compiler.
Try using a different cmake generator that's intended for your tools.
Building the shared memory hook library (SHM)
---------------------------------------------
Unlike the rest of DFHack, The SHM needs special treatment when it comes to compilation.
Because it shares the memory space with DF itself, it has to be built with the same tools as DF
and use the same C and C++/STL libraries.
For DF 40d15 - 40d17 on Windows, use MSVC 2008. You can get the Express edition for free from Microsoft.
Windows dependencies can be determined by a tool like depends.exe (google it). Both the fake SDL.dll
and DF have to use the same version of the C runtime (MSVCRT).
The SHM can't be debugged, because debug builds in MSVC use a different CRT!
Linux dependencies can be determined by setting the LD_DEBUG variable and running ./df:
export LD_DEBUG=versions
./df
Example of (a part of a) relevant output from a working SHM installation:
24472: checking for version `GLIBC_2.0' in file /opt/lib32/lib/libpthread.so.0 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GCC_3.0' in file ./libs/libgcc_s.so.1 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GLIBC_2.0' in file ./libs/libgcc_s.so.1 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GLIBC_2.1' in file /opt/lib32/lib/libm.so.6 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GLIBC_2.0' in file /opt/lib32/lib/libm.so.6 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GLIBC_2.1.3' in file /opt/lib32/lib/libc.so.6 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GLIBC_2.3.4' in file /opt/lib32/lib/libc.so.6 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GLIBC_2.4' in file /opt/lib32/lib/libc.so.6 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GLIBC_2.0' in file /opt/lib32/lib/libc.so.6 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GLIBCXX_3.4.9' in file ./libs/libstdc++.so.6 [0] required by file ./dwarfort.exe [0]
24472: checking for version `CXXABI_1.3' in file ./libs/libstdc++.so.6 [0] required by file ./dwarfort.exe [0]
24472: checking for version `GLIBCXX_3.4' in file ./libs/libstdc++.so.6 [0] required by file ./dwarfort.exe [0]
24472: checking for version `CXXABI_1.3' in file ./libs/libstdc++.so.6 [0] required by file ./libs/libdfconnect.so [0]
24472: checking for version `GLIBCXX_3.4' in file ./libs/libstdc++.so.6 [0] required by file ./libs/libdfconnect.so [0]
24472: checking for version `GLIBC_2.1.3' in file /opt/lib32/lib/libc.so.6 [0] required by file ./libs/libdfconnect.so [0]
24472: checking for version `GLIBC_2.2' in file /opt/lib32/lib/libc.so.6 [0] required by file ./libs/libdfconnect.so [0]
24472: checking for version `GLIBC_2.3.4' in file /opt/lib32/lib/libc.so.6 [0] required by file ./libs/libdfconnect.so [0]
24472: checking for version `GLIBC_2.0' in file /opt/lib32/lib/libc.so.6 [0] required by file ./libs/libdfconnect.so [0]
libdfconnect is the SHM. Both are compiled against the same C++ library and share the same CXXABI version.
Precompiled SHM libraries are provided in binary releases.
* Checking strings support
Strings are one of the important C++ types and a great indicator that the SHM works. Tools like Dwarf Therapist depend
on string support. Reading of strings can be checked by running any of the tools that deal with materials.
String writing is best tested with a fresh throw-away fort and dfrenamer. Embark, give one dwarf a very long name using dfrenamer
and save/exit. If DF crashes during the save sequence, your SHM is not compatible with DF and the throw-away fort is lost.
Build targets
-------------
dfhack has a few build targets. If you're only after the library run 'make dfhack'.
'make' will build everything.
'make expbench' will build the expbench throughput testing program and the library.
Build types
-----------
cmake allows you to pick a build type by changing this variable: CMAKE_BUILD_TYPE
cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE

122
README
Unescape Escape View File

@ -1,66 +1,84 @@
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.
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
It is also available on github:
http://github.com/peterix/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 :)
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
40d9 - 40d17
* Linux
40d9 - 40d16
40d9 - 40d17
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 :)
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.
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!!!!
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.
!!! on Windows this currently only works with DF 40d15, 40d16 and 40d17 !!!
On Linux, it works with the whole range of supported DF versions.
!!! use the pre-compiled library intended for your version of DF !!!
You can find them in the 'precompiled' folder.
** 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
- Open your DF folder, locate SDL.dll and rename it to SDLreal.dll (making
a backup of it is a good idea)
- Copy the right DFHack SDL.dll into your DF folder.
- Restart DF if it is running
** Unistalling on Windows
- Open your DF folder, locate SDL.dll and delete it
- Rename SDLreal.dll to SDl.dll
- Rename SDLreal.dll to SDL.dll
- Restart DF if it is running
@ -94,56 +112,40 @@ export LD_PRELOAD="./libs/libdfconnect.so" # Hack DF!
- 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.
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.
* 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')
If the tool writes back to DF's memory, make sure you are using the shared
memory interface mentioned in the previous section!
* 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.
* reveal - plain old reveal tool. It reveals all the map blocks already
initialized by DF.
* dfattachtest - Benchmark for the Attach, Detach, Suspend and Resume functions
* 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')
* dfbuildingsdump - exports some basic data about buildings of a given type on the game map
* cleanmap - cleans mud, vomit, snow and all kinds of mess from the map.
It will clean your irrigated farms too, so consider yourself
warned.
* dfcreaturedump - exports some basic data about all the dwarves
* dfincremental - incremental search utility.
* dfcustomCreatureNameProf - allws you to change nicknames and custom professions of your dwarves
* bauxite - converts all mechanisms into bauxite mechanisms.
* dfincremental - incremental search utility - linux only right now
* itemdesignator - Allows mass-designating items by type and material - dump,
forbid, melt and set on fire ;)
* 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.
The file with memory offset definitions used by dfhack can be found in the
output folder.
~ EOF ~

63
examples/CMakeLists.txt
Unescape Escape View File

@ -0,0 +1,63 @@
# don't use this file directly. use the one in the root folder of the project
# this is required to ensure we use the right configuration for the system.
IF(UNIX)
add_definitions(-DLINUX_BUILD)
ENDIF(UNIX)
# attachtest - 100x attach/detach, suspend/resume
ADD_EXECUTABLE(dfattachtest attachtest.cpp)
TARGET_LINK_LIBRARIES(dfattachtest dfhack)
# a benchmark program, reads the map 1000x
ADD_EXECUTABLE(dfexpbench expbench.cpp)
TARGET_LINK_LIBRARIES(dfexpbench dfhack)
# creaturedump - basic creature dump - a test of the creature related exports
ADD_EXECUTABLE(dfcreaturedump creaturedump.cpp)
TARGET_LINK_LIBRARIES(dfcreaturedump dfhack)
# buildingsdump - dump buildings and their raw data filtered by type
ADD_EXECUTABLE(dfbuildingsdump buildingsdump.cpp)
TARGET_LINK_LIBRARIES(dfbuildingsdump dfhack)
# materialtest - just list the first material of each type
ADD_EXECUTABLE(dfmaterialtest materialtest.cpp)
TARGET_LINK_LIBRARIES(dfmaterialtest dfhack)
# position - check the DF window and cursor parameters
ADD_EXECUTABLE(dfposition position.cpp)
TARGET_LINK_LIBRARIES(dfposition dfhack)
# suspendtest - test if suspend works. df should stop responding when suspended by dfhack
ADD_EXECUTABLE(dfsuspend suspendtest.cpp)
TARGET_LINK_LIBRARIES(dfsuspend dfhack)
# itemdump - dump the item under the cursor
ADD_EXECUTABLE(dfitemdump dfitemdump.cpp)
TARGET_LINK_LIBRARIES(dfitemdump dfhack)
# digger - designate for digging by tile class
# Author: mizipzor
ADD_EXECUTABLE(dfdigger digger.cpp)
TARGET_LINK_LIBRARIES(dfdigger dfhack)
# renamer - change the custom names and professions of creatures, sends keys to df directly
ADD_EXECUTABLE(dfrenamer renamer.cpp)
TARGET_LINK_LIBRARIES(dfrenamer dfhack)
IF(UNIX)
install(TARGETS
dfattachtest
dfbuildingsdump
dfcreaturedump
dfitemdump
dfdigger
dfexpbench
dfmaterialtest
dfposition
dfrenamer
dfsuspend
RUNTIME DESTINATION bin
)
ENDIF(UNIX)

0
tools/attachtest.cpp → examples/attachtest.cpp
Unescape Escape View File

0
tools/buildingsdump.cpp → examples/buildingsdump.cpp
Unescape Escape View File

0
tools/creaturedump.cpp → examples/creaturedump.cpp
Unescape Escape View File

0
tools/dfitemdump.cpp → examples/dfitemdump.cpp
Unescape Escape View File

0
tools/digger.cpp → examples/digger.cpp
Unescape Escape View File

0
tools/expbench.cpp → examples/expbench.cpp
Unescape Escape View File

0
tools/materialtest.cpp → examples/materialtest.cpp
Unescape Escape View File

0
tools/position.cpp → examples/position.cpp
Unescape Escape View File

0
tools/customCreatureNameProf.cpp → examples/renamer.cpp
Unescape Escape View File

0
tools/suspendtest.cpp → examples/suspendtest.cpp
Unescape Escape View File

2
library/DFHackAPI.cpp
Unescape Escape View File

@ -1301,7 +1301,7 @@ bool API::InitReadItems(uint32_t & numitems)
}
bool API::ReadItem (const uint32_t &index, t_item & item)
{
assert (d->buildingsInited && d->itemsInited); //should change to the generic init rather than buildings
assert (d->itemsInited); //should change to the generic init rather than buildings
t_item_df40d item_40d;
// read pointer from vector at position

58
tools/CMakeLists.txt
Unescape Escape View File

@ -5,10 +5,6 @@ IF(UNIX)
add_definitions(-DLINUX_BUILD)
ENDIF(UNIX)
# a benchmark program, reads the map 1000x
ADD_EXECUTABLE(dfexpbench expbench.cpp)
TARGET_LINK_LIBRARIES(dfexpbench dfhack)
# a reveal clone
ADD_EXECUTABLE(dfreveal reveal.cpp)
TARGET_LINK_LIBRARIES(dfreveal dfhack)
@ -21,75 +17,27 @@ TARGET_LINK_LIBRARIES(dfprospector dfhack)
ADD_EXECUTABLE(dfcleanmap cleanmap.cpp)
TARGET_LINK_LIBRARIES(dfcleanmap dfhack)
# creaturedump - basic creature dump - a test of the creature related exports
ADD_EXECUTABLE(dfcreaturedump creaturedump.cpp)
TARGET_LINK_LIBRARIES(dfcreaturedump dfhack)
# buildingsdump - dump buildings and their raw data filtered by type
ADD_EXECUTABLE(dfbuildingsdump buildingsdump.cpp)
TARGET_LINK_LIBRARIES(dfbuildingsdump dfhack)
# attachtest - 100x attach/detach, 100x reads, 100x writes
ADD_EXECUTABLE(dfattachtest attachtest.cpp)
TARGET_LINK_LIBRARIES(dfattachtest dfhack)
# materialtest - just list the first material of each type
ADD_EXECUTABLE(dfmaterialtest materialtest.cpp)
TARGET_LINK_LIBRARIES(dfmaterialtest dfhack)
# materialtest - just list the first material of each type
ADD_EXECUTABLE(dfposition position.cpp)
TARGET_LINK_LIBRARIES(dfposition dfhack)
#currently only stable on linux
IF(UNIX)
# incremental - incremental memory search tool, a foreshadowing of the future direction of dfhack
# incrementalsearch - a bit like cheat engine, only DF-specific and very basic
ADD_EXECUTABLE(dfincremental incrementalsearch.cpp)
TARGET_LINK_LIBRARIES(dfincremental dfhack)
ENDIF(UNIX)
# suspendtest - test if suspend works. df should stop responding when suspended by dfhack
ADD_EXECUTABLE(dfsuspend suspendtest.cpp)
TARGET_LINK_LIBRARIES(dfsuspend dfhack)
# itemdump - dump the item under the cursor
ADD_EXECUTABLE(dfitemdump dfitemdump.cpp)
TARGET_LINK_LIBRARIES(dfitemdump dfhack)
# bauxite - turn all mechanisms into bauxite mechanisms
# Author: Alex Legg
ADD_EXECUTABLE(dfbauxite dfbauxite.cpp)
TARGET_LINK_LIBRARIES(dfbauxite dfhack)
# digger - designate for digging by tile class
# Author: mizipzor
ADD_EXECUTABLE(dfdigger digger.cpp)
TARGET_LINK_LIBRARIES(dfdigger dfhack)
# itemdesignator - change some item designations (dump, forbid, on-fire) for all items of a given type and material
ADD_EXECUTABLE(dfitemdesignator itemdesignator.cpp)
TARGET_LINK_LIBRARIES(dfitemdesignator dfhack)
# customCtreatureNameProf - change the custom names and professions of creatures, sends keys to df directly
ADD_EXECUTABLE(dfcustomCreatureNameProf customCreatureNameProf.cpp)
TARGET_LINK_LIBRARIES(dfcustomCreatureNameProf dfhack)
IF(UNIX)
install(TARGETS
dfexpbench
dfreveal
dfreveal
dfprospector
dfcleanmap
dfcreaturedump
dfattachtest
dfmaterialtest
dfbuildingsdump
dfposition
dfincremental
dfitemdump
dfsuspend
dfbauxite
dfitemdesignator
RUNTIME DESTINATION bin
)
ENDIF(UNIX)