summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlexander Gavrilov2012-06-22 20:41:15 +0400
committerAlexander Gavrilov2012-06-22 20:41:15 +0400
commit0e582901ee972853999dfc86dbe93093a65cd35b (patch)
tree57aed3a9ff6a951d29310b086b9a7329eb4e64b9
parentbd37cc09c525d4db9400e224e4ca3cadcf0eed4c (diff)
downloaddfhack-0e582901ee972853999dfc86dbe93093a65cd35b.tar.gz
dfhack-0e582901ee972853999dfc86dbe93093a65cd35b.tar.bz2
dfhack-0e582901ee972853999dfc86dbe93093a65cd35b.tar.xz
Update the compile document with some info about df-structures and RPC.
-rw-r--r--COMPILE.rst23
-rw-r--r--Compile.html33
-rw-r--r--Readme.html7
3 files changed, 52 insertions, 11 deletions
diff --git a/COMPILE.rst b/COMPILE.rst
index beb73836..8fca0e1f 100644
--- a/COMPILE.rst
+++ b/COMPILE.rst
@@ -152,10 +152,13 @@ Valid and useful build types include 'Release', 'Debug' and
================================
Using the library as a developer
================================
-Currently, the only way to use the library is to write a plugin that can be loaded by it.
+
+Currently, the most direct way to use the library is to write a plugin that can be loaded by it.
All the plugins can be found in the 'plugins' folder. There's no in-depth documentation
on how to write one yet, but it should be easy enough to copy one and just follow the pattern.
+Other than through plugins, it is possible to use DFHack via remote access interface, or by writing Lua scripts.
+
The most important parts of DFHack are the Core, Console, Modules and Plugins.
* Core acts as the centerpiece of DFHack - it acts as a filter between DF and SDL and synchronizes the various plugins with DF.
@@ -171,6 +174,24 @@ The main license is zlib/libpng, some bits are MIT licensed, and some are BSD li
Feel free to add your own extensions and plugins. Contributing back to
the dfhack repository is welcome and the right thing to do :)
+DF data structure definitions
+=============================
+
+DFHack uses information about the game data structures, represented via xml files in the library/xml/ submodule.
+
+Data structure layouts are described in files following the df.*.xml name pattern. This information is transformed by a perl script into C++ headers describing the structures, and associated metadata for the Lua wrapper. These headers and data are then compiled into the DFHack libraries, thus necessitating a compatibility break every time layouts change; in return it significantly boosts the efficiency and capabilities of DFHack code.
+
+Global object addresses are stored in symbols.xml, which is copied to the dfhack release package and loaded as data at runtime.
+
+Remote access interface
+=======================
+
+DFHack supports remote access by exchanging Google protobuf messages via a TCP socket. Both the core and plugins can define remotely accessible methods. The ``dfhack-run`` command uses this interface to invoke ordinary console commands.
+
+Currently the supported set of requests is limited, because the developers don't know what exactly is most useful.
+
+Protocol client implementations exist for Java and C#.
+
Contributing to DFHack
======================
diff --git a/Compile.html b/Compile.html
index b0f9e9c6..e17e57e2 100644
--- a/Compile.html
+++ b/Compile.html
@@ -334,10 +334,12 @@ ul.auto-toc {
</li>
<li><a class="reference internal" href="#build-types" id="id12">Build types</a></li>
<li><a class="reference internal" href="#using-the-library-as-a-developer" id="id13">Using the library as a developer</a><ul>
-<li><a class="reference internal" href="#contributing-to-dfhack" id="id14">Contributing to DFHack</a><ul>
-<li><a class="reference internal" href="#coding-style" id="id15">Coding style</a></li>
-<li><a class="reference internal" href="#how-to-get-new-code-into-dfhack" id="id16">How to get new code into DFHack</a></li>
-<li><a class="reference internal" href="#memory-research" id="id17">Memory research</a></li>
+<li><a class="reference internal" href="#df-data-structure-definitions" id="id14">DF data structure definitions</a></li>
+<li><a class="reference internal" href="#remote-access-interface" id="id15">Remote access interface</a></li>
+<li><a class="reference internal" href="#contributing-to-dfhack" id="id16">Contributing to DFHack</a><ul>
+<li><a class="reference internal" href="#coding-style" id="id17">Coding style</a></li>
+<li><a class="reference internal" href="#how-to-get-new-code-into-dfhack" id="id18">How to get new code into DFHack</a></li>
+<li><a class="reference internal" href="#memory-research" id="id19">Memory research</a></li>
</ul>
</li>
</ul>
@@ -470,9 +472,10 @@ cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE
</div>
<div class="section" id="using-the-library-as-a-developer">
<h1><a class="toc-backref" href="#id13">Using the library as a developer</a></h1>
-<p>Currently, the only way to use the library is to write a plugin that can be loaded by it.
+<p>Currently, the most direct way to use the library is to write a plugin that can be loaded by it.
All the plugins can be found in the 'plugins' folder. There's no in-depth documentation
on how to write one yet, but it should be easy enough to copy one and just follow the pattern.</p>
+<p>Other than through plugins, it is possible to use DFHack via remote access interface, or by writing Lua scripts.</p>
<p>The most important parts of DFHack are the Core, Console, Modules and Plugins.</p>
<ul class="simple">
<li>Core acts as the centerpiece of DFHack - it acts as a filter between DF and SDL and synchronizes the various plugins with DF.</li>
@@ -485,18 +488,30 @@ on how to write one yet, but it should be easy enough to copy one and just follo
The main license is zlib/libpng, some bits are MIT licensed, and some are BSD licensed.</p>
<p>Feel free to add your own extensions and plugins. Contributing back to
the dfhack repository is welcome and the right thing to do :)</p>
+<div class="section" id="df-data-structure-definitions">
+<h2><a class="toc-backref" href="#id14">DF data structure definitions</a></h2>
+<p>DFHack uses information about the game data structures, represented via xml files in the library/xml/ submodule.</p>
+<p>Data structure layouts are described in files following the df.*.xml name pattern. This information is transformed by a perl script into C++ headers describing the structures, and associated metadata for the Lua wrapper. These headers and data are then compiled into the DFHack libraries, thus necessitating a compatibility break every time layouts change; in return it significantly boosts the efficiency and capabilities of DFHack code.</p>
+<p>Global object addresses are stored in symbols.xml, which is copied to the dfhack release package and loaded as data at runtime.</p>
+</div>
+<div class="section" id="remote-access-interface">
+<h2><a class="toc-backref" href="#id15">Remote access interface</a></h2>
+<p>DFHack supports remote access by exchanging Google protobuf messages via a TCP socket. Both the core and plugins can define remotely accessible methods. The <tt class="docutils literal"><span class="pre">dfhack-run</span></tt> command uses this interface to invoke ordinary console commands.</p>
+<p>Currently the supported set of requests is limited, because the developers don't know what exactly is most useful.</p>
+<p>Protocol client implementations exist for Java and C#.</p>
+</div>
<div class="section" id="contributing-to-dfhack">
-<h2><a class="toc-backref" href="#id14">Contributing to DFHack</a></h2>
+<h2><a class="toc-backref" href="#id16">Contributing to DFHack</a></h2>
<p>Several things should be kept in mind when contributing to DFHack.</p>
<div class="section" id="coding-style">
-<h3><a class="toc-backref" href="#id15">Coding style</a></h3>
+<h3><a class="toc-backref" href="#id17">Coding style</a></h3>
<p>DFhack uses ANSI formatting and four spaces as indentation. Line
endings are UNIX. The files use UTF-8 encoding. Code not following this
won't make me happy, because I'll have to fix it. There's a good chance
I'll make <em>you</em> fix it ;)</p>
</div>
<div class="section" id="how-to-get-new-code-into-dfhack">
-<h3><a class="toc-backref" href="#id16">How to get new code into DFHack</a></h3>
+<h3><a class="toc-backref" href="#id18">How to get new code into DFHack</a></h3>
<p>You can send patches or make a clone of the github repo and ask me on
the IRC channel to pull your code in. I'll review it and see if there
are any problems. I'll fix them if they are minor.</p>
@@ -506,7 +521,7 @@ this is also a good place to dump new ideas and/or bugs that need
fixing.</p>
</div>
<div class="section" id="memory-research">
-<h3><a class="toc-backref" href="#id17">Memory research</a></h3>
+<h3><a class="toc-backref" href="#id19">Memory research</a></h3>
<p>If you want to do memory research, you'll need some tools and some knowledge.
In general, you'll need a good memory viewer and optionally something
to look at machine code without getting crazy :)</p>
diff --git a/Readme.html b/Readme.html
index cd579d37..50ceae99 100644
--- a/Readme.html
+++ b/Readme.html
@@ -1350,7 +1350,12 @@ produce undesirable results. There are a few good ones though.</p>
<p class="last">You are in fort game mode, managing your fortress and paused.
You switch to the arena game mode, <em>assume control of a creature</em> and then
switch to adventure game mode(1).
-You just lost a fortress and gained an adventurer.</p>
+You just lost a fortress and gained an adventurer.
+You could also do this.
+You are in fort game mode, managing your fortress and paused at the esc menu.
+You switch to the adventure game mode, then use Dfusion to <em>assume control of a creature</em> and then
+save or retire.
+You just created a returnable mountain home and gained an adventurer.</p>
</div>
<p>I take no responsibility of anything that happens as a result of using this tool</p>
</div>