develop
Quietust 2012-06-22 07:47:10 -05:00
commit dedc59c709
12 changed files with 709 additions and 101 deletions

@ -426,13 +426,17 @@ not destroy any objects allocated in this way, so the user
should be prepared to catch the error and do the necessary
cleanup.
================
DFHack utilities
================
==========
DFHack API
==========
DFHack utility functions are placed in the ``dfhack`` global tree.
Currently it defines the following features:
Native utilities
================
Input & Output
--------------
* ``dfhack.print(args...)``
@ -451,6 +455,7 @@ Currently it defines the following features:
* ``dfhack.color([color])``
Sets the current output color. If color is *nil* or *-1*, resets to default.
Returns the previous color value.
* ``dfhack.is_interactive()``
@ -473,23 +478,9 @@ Currently it defines the following features:
If the interactive console is not accessible, returns *nil, error*.
* ``dfhack.pcall(f[,args...])``
Invokes f via xpcall, using an error function that attaches
a stack trace to the error. The same function is used by SafeCall
in C++, and dfhack.safecall.
The returned error is a table with separate ``message`` and
``stacktrace`` string fields; it implements ``__tostring``.
* ``safecall(f[,args...])``, ``dfhack.safecall(f[,args...])``
Just like pcall, but also prints the error using printerr before
returning. Intended as a convenience function.
* ``dfhack.saferesume(coroutine[,args...])``
Compares to coroutine.resume like dfhack.safecall vs pcall.
Miscellaneous
-------------
* ``dfhack.run_script(name[,args...])``
@ -510,6 +501,36 @@ Currently it defines the following features:
to group operations together in one big critical section. A plugin
can choose to run all lua code inside a C++-side suspend lock.
Exception handling
------------------
* ``dfhack.error(msg[,level[,verbose]])``
Throws a dfhack exception object with location and stack trace.
The verbose parameter controls whether the trace is printed by default.
* ``qerror(msg[,level])``
Calls ``dfhack.error()`` with ``verbose`` being *false*. Intended to
be used for user-caused errors in scripts, where stack traces are not
desirable.
* ``dfhack.pcall(f[,args...])``
Invokes f via xpcall, using an error function that attaches
a stack trace to the error. The same function is used by SafeCall
in C++, and dfhack.safecall.
* ``safecall(f[,args...])``, ``dfhack.safecall(f[,args...])``
Just like pcall, but also prints the error using printerr before
returning. Intended as a convenience function.
* ``dfhack.saferesume(coroutine[,args...])``
Compares to coroutine.resume like dfhack.safecall vs pcall.
* ``dfhack.call_with_finalizer(num_cleanup_args,always,cleanup_fn[,cleanup_args...],fn[,args...])``
Invokes ``fn`` with ``args``, and after it returns or throws an
@ -534,9 +555,33 @@ Currently it defines the following features:
Calls ``fn(obj,args...)``, then finalizes with ``obj:delete()``.
* ``dfhack.exception``
Metatable of error objects used by dfhack. The objects have the
following properties:
``err.where``
The location prefix string, or *nil*.
``err.message``
The base message string.
``err.stacktrace``
The stack trace string, or *nil*.
``err.cause``
A different exception object, or *nil*.
``err.thread``
The coroutine that has thrown the exception.
``err.verbose``
Boolean, or *nil*; specifies if where and stacktrace should be printed.
``tostring(err)``, or ``err:tostring([verbose])``
Converts the exception to string.
* ``dfhack.exception.verbose``
The default value of the ``verbose`` argument of ``err:tostring()``.
Persistent configuration storage
================================
--------------------------------
This api is intended for storing configuration options in the world itself.
It probably should be restricted to data that is world-dependent.
@ -578,7 +623,7 @@ functions can just copy values in memory without doing any actual I/O.
However, currently every entry has a 180+-byte dead-weight overhead.
Material info lookup
====================
--------------------
A material info record has fields:

@ -333,30 +333,36 @@ ul.auto-toc {
<li><a class="reference internal" href="#recursive-table-assignment" id="id9">Recursive table assignment</a></li>
</ul>
</li>
<li><a class="reference internal" href="#dfhack-utilities" id="id10">DFHack utilities</a><ul>
<li><a class="reference internal" href="#persistent-configuration-storage" id="id11">Persistent configuration storage</a></li>
<li><a class="reference internal" href="#material-info-lookup" id="id12">Material info lookup</a></li>
<li><a class="reference internal" href="#c-function-wrappers" id="id13">C++ function wrappers</a><ul>
<li><a class="reference internal" href="#gui-module" id="id14">Gui module</a></li>
<li><a class="reference internal" href="#job-module" id="id15">Job module</a></li>
<li><a class="reference internal" href="#units-module" id="id16">Units module</a></li>
<li><a class="reference internal" href="#items-module" id="id17">Items module</a></li>
<li><a class="reference internal" href="#maps-module" id="id18">Maps module</a></li>
<li><a class="reference internal" href="#burrows-module" id="id19">Burrows module</a></li>
<li><a class="reference internal" href="#buildings-module" id="id20">Buildings module</a></li>
<li><a class="reference internal" href="#constructions-module" id="id21">Constructions module</a></li>
<li><a class="reference internal" href="#internal-api" id="id22">Internal API</a></li>
<li><a class="reference internal" href="#dfhack-api" id="id10">DFHack API</a><ul>
<li><a class="reference internal" href="#native-utilities" id="id11">Native utilities</a><ul>
<li><a class="reference internal" href="#input-output" id="id12">Input &amp; Output</a></li>
<li><a class="reference internal" href="#miscellaneous" id="id13">Miscellaneous</a></li>
<li><a class="reference internal" href="#exception-handling" id="id14">Exception handling</a></li>
<li><a class="reference internal" href="#persistent-configuration-storage" id="id15">Persistent configuration storage</a></li>
<li><a class="reference internal" href="#material-info-lookup" id="id16">Material info lookup</a></li>
</ul>
</li>
<li><a class="reference internal" href="#core-interpreter-context" id="id23">Core interpreter context</a><ul>
<li><a class="reference internal" href="#event-type" id="id24">Event type</a></li>
<li><a class="reference internal" href="#c-function-wrappers" id="id17">C++ function wrappers</a><ul>
<li><a class="reference internal" href="#gui-module" id="id18">Gui module</a></li>
<li><a class="reference internal" href="#job-module" id="id19">Job module</a></li>
<li><a class="reference internal" href="#units-module" id="id20">Units module</a></li>
<li><a class="reference internal" href="#items-module" id="id21">Items module</a></li>
<li><a class="reference internal" href="#maps-module" id="id22">Maps module</a></li>
<li><a class="reference internal" href="#burrows-module" id="id23">Burrows module</a></li>
<li><a class="reference internal" href="#buildings-module" id="id24">Buildings module</a></li>
<li><a class="reference internal" href="#constructions-module" id="id25">Constructions module</a></li>
<li><a class="reference internal" href="#internal-api" id="id26">Internal API</a></li>
</ul>
</li>
<li><a class="reference internal" href="#core-interpreter-context" id="id27">Core interpreter context</a><ul>
<li><a class="reference internal" href="#event-type" id="id28">Event type</a></li>
</ul>
</li>
<li><a class="reference internal" href="#plugins" id="id25">Plugins</a><ul>
<li><a class="reference internal" href="#burrows" id="id26">burrows</a></li>
<li><a class="reference internal" href="#sort" id="id27">sort</a></li>
</ul>
</li>
<li><a class="reference internal" href="#plugins" id="id29">Plugins</a><ul>
<li><a class="reference internal" href="#burrows" id="id30">burrows</a></li>
<li><a class="reference internal" href="#sort" id="id31">sort</a></li>
</ul>
</li>
</ul>
@ -717,10 +723,13 @@ should be prepared to catch the error and do the necessary
cleanup.</p>
</div>
</div>
<div class="section" id="dfhack-utilities">
<h1><a class="toc-backref" href="#id10">DFHack utilities</a></h1>
<div class="section" id="dfhack-api">
<h1><a class="toc-backref" href="#id10">DFHack API</a></h1>
<p>DFHack utility functions are placed in the <tt class="docutils literal">dfhack</tt> global tree.</p>
<p>Currently it defines the following features:</p>
<div class="section" id="native-utilities">
<h2><a class="toc-backref" href="#id11">Native utilities</a></h2>
<div class="section" id="input-output">
<h3><a class="toc-backref" href="#id12">Input &amp; Output</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.print(args...)</span></tt></p>
<p>Output tab-separated args as standard lua print would do,
@ -734,7 +743,8 @@ works with DFHack output infrastructure.</p>
<p>Same as println; intended for errors. Uses red color and logs to stderr.log.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.color([color])</span></tt></p>
<p>Sets the current output color. If color is <em>nil</em> or <em>-1</em>, resets to default.</p>
<p>Sets the current output color. If color is <em>nil</em> or <em>-1</em>, resets to default.
Returns the previous color value.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.is_interactive()</tt></p>
<p>Checks if the thread can access the interactive console and returns <em>true</em> or <em>false</em>.</p>
@ -752,20 +762,11 @@ this, forcing the function to block on input with lock held.</p>
string, global environment and command-line history file.</p>
<p>If the interactive console is not accessible, returns <em>nil, error</em>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.pcall(f[,args...])</span></tt></p>
<p>Invokes f via xpcall, using an error function that attaches
a stack trace to the error. The same function is used by SafeCall
in C++, and dfhack.safecall.</p>
<p>The returned error is a table with separate <tt class="docutils literal">message</tt> and
<tt class="docutils literal">stacktrace</tt> string fields; it implements <tt class="docutils literal">__tostring</tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">safecall(f[,args...])</span></tt>, <tt class="docutils literal"><span class="pre">dfhack.safecall(f[,args...])</span></tt></p>
<p>Just like pcall, but also prints the error using printerr before
returning. Intended as a convenience function.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.saferesume(coroutine[,args...])</span></tt></p>
<p>Compares to coroutine.resume like dfhack.safecall vs pcall.</p>
</li>
</ul>
</div>
<div class="section" id="miscellaneous">
<h3><a class="toc-backref" href="#id13">Miscellaneous</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.run_script(name[,args...])</span></tt></p>
<p>Run a lua script in hack/scripts/, as if it was started from dfhack command-line.
The <tt class="docutils literal">name</tt> argument should be the name stem, as would be used on the command line.
@ -781,6 +782,32 @@ the lock. It is safe to nest suspends.</p>
to group operations together in one big critical section. A plugin
can choose to run all lua code inside a C++-side suspend lock.</p>
</li>
</ul>
</div>
<div class="section" id="exception-handling">
<h3><a class="toc-backref" href="#id14">Exception handling</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.error(msg[,level[,verbose]])</span></tt></p>
<p>Throws a dfhack exception object with location and stack trace.
The verbose parameter controls whether the trace is printed by default.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">qerror(msg[,level])</span></tt></p>
<p>Calls <tt class="docutils literal">dfhack.error()</tt> with <tt class="docutils literal">verbose</tt> being <em>false</em>. Intended to
be used for user-caused errors in scripts, where stack traces are not
desirable.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.pcall(f[,args...])</span></tt></p>
<p>Invokes f via xpcall, using an error function that attaches
a stack trace to the error. The same function is used by SafeCall
in C++, and dfhack.safecall.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">safecall(f[,args...])</span></tt>, <tt class="docutils literal"><span class="pre">dfhack.safecall(f[,args...])</span></tt></p>
<p>Just like pcall, but also prints the error using printerr before
returning. Intended as a convenience function.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.saferesume(coroutine[,args...])</span></tt></p>
<p>Compares to coroutine.resume like dfhack.safecall vs pcall.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.call_with_finalizer(num_cleanup_args,always,cleanup_fn[,cleanup_args...],fn[,args...])</span></tt></p>
<p>Invokes <tt class="docutils literal">fn</tt> with <tt class="docutils literal">args</tt>, and after it returns or throws an
error calls <tt class="docutils literal">cleanup_fn</tt> with <tt class="docutils literal">cleanup_args</tt>. Any return values from
@ -800,9 +827,40 @@ Implemented using <tt class="docutils literal"><span class="pre">call_with_final
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.with_temp_object(obj,fn[,args...])</span></tt></p>
<p>Calls <tt class="docutils literal"><span class="pre">fn(obj,args...)</span></tt>, then finalizes with <tt class="docutils literal">obj:delete()</tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.exception</tt></p>
<p>Metatable of error objects used by dfhack. The objects have the
following properties:</p>
<dl class="docutils">
<dt><tt class="docutils literal">err.where</tt></dt>
<dd><p class="first last">The location prefix string, or <em>nil</em>.</p>
</dd>
<dt><tt class="docutils literal">err.message</tt></dt>
<dd><p class="first last">The base message string.</p>
</dd>
<dt><tt class="docutils literal">err.stacktrace</tt></dt>
<dd><p class="first last">The stack trace string, or <em>nil</em>.</p>
</dd>
<dt><tt class="docutils literal">err.cause</tt></dt>
<dd><p class="first last">A different exception object, or <em>nil</em>.</p>
</dd>
<dt><tt class="docutils literal">err.thread</tt></dt>
<dd><p class="first last">The coroutine that has thrown the exception.</p>
</dd>
<dt><tt class="docutils literal">err.verbose</tt></dt>
<dd><p class="first last">Boolean, or <em>nil</em>; specifies if where and stacktrace should be printed.</p>
</dd>
<dt><tt class="docutils literal">tostring(err)</tt>, or <tt class="docutils literal"><span class="pre">err:tostring([verbose])</span></tt></dt>
<dd><p class="first last">Converts the exception to string.</p>
</dd>
</dl>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.exception.verbose</tt></p>
<p>The default value of the <tt class="docutils literal">verbose</tt> argument of <tt class="docutils literal">err:tostring()</tt>.</p>
</li>
</ul>
</div>
<div class="section" id="persistent-configuration-storage">
<h2><a class="toc-backref" href="#id11">Persistent configuration storage</a></h2>
<h3><a class="toc-backref" href="#id15">Persistent configuration storage</a></h3>
<p>This api is intended for storing configuration options in the world itself.
It probably should be restricted to data that is world-dependent.</p>
<p>Entries are identified by a string <tt class="docutils literal">key</tt>, but it is also possible to manage
@ -837,7 +895,7 @@ functions can just copy values in memory without doing any actual I/O.
However, currently every entry has a 180+-byte dead-weight overhead.</p>
</div>
<div class="section" id="material-info-lookup">
<h2><a class="toc-backref" href="#id12">Material info lookup</a></h2>
<h3><a class="toc-backref" href="#id16">Material info lookup</a></h3>
<p>A material info record has fields:</p>
<ul>
<li><p class="first"><tt class="docutils literal">type</tt>, <tt class="docutils literal">index</tt>, <tt class="docutils literal">material</tt></p>
@ -880,8 +938,9 @@ Accept dfhack_material_category auto-assign table.</p>
</li>
</ul>
</div>
</div>
<div class="section" id="c-function-wrappers">
<h2><a class="toc-backref" href="#id13">C++ function wrappers</a></h2>
<h2><a class="toc-backref" href="#id17">C++ function wrappers</a></h2>
<p>Thin wrappers around C++ functions, similar to the ones for virtual methods.
One notable difference is that these explicit wrappers allow argument count
adjustment according to the usual lua rules, so trailing false/nil arguments
@ -910,7 +969,7 @@ can be omitted.</p>
</li>
</ul>
<div class="section" id="gui-module">
<h3><a class="toc-backref" href="#id14">Gui module</a></h3>
<h3><a class="toc-backref" href="#id18">Gui module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.gui.getCurViewscreen()</tt></p>
<p>Returns the viewscreen that is current in the core.</p>
@ -946,7 +1005,7 @@ The is_bright boolean actually seems to invert the brightness.</p>
</ul>
</div>
<div class="section" id="job-module">
<h3><a class="toc-backref" href="#id15">Job module</a></h3>
<h3><a class="toc-backref" href="#id19">Job module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.job.cloneJobStruct(job)</tt></p>
<p>Creates a deep copy of the given job.</p>
@ -983,7 +1042,7 @@ a lua list containing them.</p>
</ul>
</div>
<div class="section" id="units-module">
<h3><a class="toc-backref" href="#id16">Units module</a></h3>
<h3><a class="toc-backref" href="#id20">Units module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.units.getPosition(unit)</tt></p>
<p>Returns true <em>x,y,z</em> of the unit, or <em>nil</em> if invalid; may be not equal to unit.pos if caged.</p>
@ -1037,7 +1096,7 @@ or raws. The <tt class="docutils literal">ignore_noble</tt> boolean disables the
</ul>
</div>
<div class="section" id="items-module">
<h3><a class="toc-backref" href="#id17">Items module</a></h3>
<h3><a class="toc-backref" href="#id21">Items module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.items.getPosition(item)</tt></p>
<p>Returns true <em>x,y,z</em> of the item, or <em>nil</em> if invalid; may be not equal to item.pos if in inventory.</p>
@ -1080,7 +1139,7 @@ Returns <em>false</em> in case of error.</p>
</ul>
</div>
<div class="section" id="maps-module">
<h3><a class="toc-backref" href="#id18">Maps module</a></h3>
<h3><a class="toc-backref" href="#id22">Maps module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.maps.getSize()</tt></p>
<p>Returns map size in blocks: <em>x, y, z</em></p>
@ -1121,7 +1180,7 @@ burrows, or the presence of invaders.</p>
</ul>
</div>
<div class="section" id="burrows-module">
<h3><a class="toc-backref" href="#id19">Burrows module</a></h3>
<h3><a class="toc-backref" href="#id23">Burrows module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.burrows.findByName(name)</tt></p>
<p>Returns the burrow pointer or <em>nil</em>.</p>
@ -1156,7 +1215,7 @@ burrows, or the presence of invaders.</p>
</ul>
</div>
<div class="section" id="buildings-module">
<h3><a class="toc-backref" href="#id20">Buildings module</a></h3>
<h3><a class="toc-backref" href="#id24">Buildings module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.buildings.getSize(building)</tt></p>
<p>Returns <em>width, height, centerx, centery</em>.</p>
@ -1296,7 +1355,7 @@ can be determined this way, <tt class="docutils literal">constructBuilding</tt>
</ul>
</div>
<div class="section" id="constructions-module">
<h3><a class="toc-backref" href="#id21">Constructions module</a></h3>
<h3><a class="toc-backref" href="#id25">Constructions module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.constructions.designateNew(pos,type,item_type,mat_index)</tt></p>
<p>Designates a new construction at given position. If there already is
@ -1312,7 +1371,7 @@ Returns <em>true, was_only_planned</em> if removed; or <em>false</em> if none fo
</ul>
</div>
<div class="section" id="internal-api">
<h3><a class="toc-backref" href="#id22">Internal API</a></h3>
<h3><a class="toc-backref" href="#id26">Internal API</a></h3>
<p>These functions are intended for the use by dfhack developers,
and are only documented here for completeness:</p>
<ul>
@ -1329,8 +1388,8 @@ global environment, persistent between calls to the script.</p>
<li><p class="first"><tt class="docutils literal">dfhack.internal.getVTable(name)</tt></p>
<p>Returns the pre-extracted vtable address <tt class="docutils literal">name</tt>, or <em>nil</em>.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.internal.getBase()</tt></p>
<p>Returns the base address of the process.</p>
<li><p class="first"><tt class="docutils literal">dfhack.internal.getRebaseDelta()</tt></p>
<p>Returns the ASLR rebase offset of the DF executable.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.internal.getMemRanges()</tt></p>
<p>Returns a sequence of tables describing virtual memory ranges of the process.</p>
@ -1355,7 +1414,7 @@ Returns: <em>found_index</em>, or <em>nil</em> if end reached.</p>
</div>
</div>
<div class="section" id="core-interpreter-context">
<h2><a class="toc-backref" href="#id23">Core interpreter context</a></h2>
<h2><a class="toc-backref" href="#id27">Core interpreter context</a></h2>
<p>While plugins can create any number of interpreter instances,
there is one special context managed by dfhack core. It is the
only context that can receive events from DF and plugins.</p>
@ -1386,7 +1445,7 @@ Using <tt class="docutils literal">timeout_active(id,nil)</tt> cancels the timer
</li>
</ul>
<div class="section" id="event-type">
<h3><a class="toc-backref" href="#id24">Event type</a></h3>
<h3><a class="toc-backref" href="#id28">Event type</a></h3>
<p>An event is just a lua table with a predefined metatable that
contains a __call metamethod. When it is invoked, it loops
through the table with next and calls all contained values.
@ -1412,14 +1471,14 @@ order using <tt class="docutils literal">dfhack.safecall</tt>.</p>
</div>
</div>
<div class="section" id="plugins">
<h1><a class="toc-backref" href="#id25">Plugins</a></h1>
<h1><a class="toc-backref" href="#id29">Plugins</a></h1>
<p>DFHack plugins may export native functions and events
to lua contexts. They are automatically imported by
<tt class="docutils literal"><span class="pre">mkmodule('plugins.&lt;name&gt;')</span></tt>; this means that a lua
module file is still necessary for <tt class="docutils literal">require</tt> to read.</p>
<p>The following plugins have lua support.</p>
<div class="section" id="burrows">
<h2><a class="toc-backref" href="#id26">burrows</a></h2>
<h2><a class="toc-backref" href="#id30">burrows</a></h2>
<p>Implements extended burrow manipulations.</p>
<p>Events:</p>
<ul>
@ -1457,7 +1516,7 @@ set is the same as used by the command line.</p>
<p>The lua module file also re-exports functions from <tt class="docutils literal">dfhack.burrows</tt>.</p>
</div>
<div class="section" id="sort">
<h2><a class="toc-backref" href="#id27">sort</a></h2>
<h2><a class="toc-backref" href="#id31">sort</a></h2>
<p>Does not export any native functions as of now. Instead, it
calls lua code to perform the actual ordering of list items.</p>
</div>

@ -1036,7 +1036,7 @@ static void *checkaddr(lua_State *L, int idx, bool allow_null = false)
return rv;
}
static uint32_t getRebaseDelta() { return Core::getInstance().vinfo->getRebaseDelta(); }
static int getRebaseDelta() { return Core::getInstance().vinfo->getRebaseDelta(); }
static const LuaWrapper::FunctionReg dfhack_internal_module[] = {
WRAP(getRebaseDelta),
@ -1074,9 +1074,9 @@ static int internal_setAddress(lua_State *L)
}
// Print via printerr, so that it is definitely logged to stderr.log.
addr -= Core::getInstance().vinfo->getRebaseDelta();
std::string msg = stl_sprintf("<global-address name='%s' value='0x%x'/>", name.c_str(), addr);
dfhack_printerr(L, msg);
uint32_t iaddr = addr - Core::getInstance().vinfo->getRebaseDelta();
fprintf(stderr, "Setting global '%s' to %x (%x)\n", name.c_str(), addr, iaddr);
fflush(stderr);
return 1;
}

@ -256,8 +256,11 @@ static int lua_dfhack_color(lua_State *S)
luaL_argerror(S, 1, "invalid color value");
color_ostream *out = Lua::GetOutput(S);
if (out)
if (out) {
lua_pushinteger(S, (int)out->color());
out->color(color_ostream::color_value(cv));
return 1;
}
return 0;
}
@ -423,10 +426,12 @@ static bool convert_to_exception(lua_State *L, int slevel, lua_State *thread = N
// Create a new exception for this thread
lua_newtable(L);
luaL_where(L, 1);
luaL_where(L, slevel);
lua_setfield(L, -2, "where");
lua_pushstring(L, "coroutine resume failed");
lua_concat(L, 2);
lua_setfield(L, -2, "message");
lua_getfield(L, -2, "verbose");
lua_setfield(L, -2, "verbose");
lua_swap(L);
lua_setfield(L, -2, "cause");
}
@ -480,12 +485,57 @@ static int dfhack_onerror(lua_State *L)
return 1;
}
static int dfhack_error(lua_State *L)
{
luaL_checkany(L, 1);
lua_settop(L, 3);
int level = std::max(1, luaL_optint(L, 2, 1));
lua_pushvalue(L, 1);
if (convert_to_exception(L, level))
{
luaL_where(L, level);
lua_setfield(L, -2, "where");
if (!lua_isnil(L, 3))
{
lua_pushvalue(L, 3);
lua_setfield(L, -2, "verbose");
}
}
return lua_error(L);
}
static int dfhack_exception_tostring(lua_State *L)
{
luaL_checktype(L, 1, LUA_TTABLE);
lua_settop(L, 2);
if (lua_isnil(L, 2))
{
lua_rawgetp(L, LUA_REGISTRYINDEX, &DFHACK_EXCEPTION_META_TOKEN);
lua_getfield(L, -1, "verbose");
lua_insert(L, 2);
lua_settop(L, 2);
}
lua_getfield(L, 1, "verbose");
bool verbose =
lua_toboolean(L, 2) || lua_toboolean(L, 3) ||
(lua_isnil(L, 2) && lua_isnil(L, 3));
int base = lua_gettop(L);
if (verbose || lua_isnil(L, 3))
{
lua_getfield(L, 1, "where");
if (!lua_isstring(L, -1))
lua_pop(L, 1);
}
lua_getfield(L, 1, "message");
if (!lua_isstring(L, -1))
{
@ -493,15 +543,26 @@ static int dfhack_exception_tostring(lua_State *L)
lua_pushstring(L, "(error message is not a string)");
}
if (verbose)
{
lua_pushstring(L, "\n");
lua_getfield(L, 1, "stacktrace");
if (!lua_isstring(L, -1))
lua_pop(L, 2);
}
lua_pushstring(L, "\ncaused by:\n");
lua_getfield(L, 1, "cause");
if (lua_isnil(L, -1))
lua_pop(L, 2);
else if (lua_istable(L, -1))
{
lua_pushcfunction(L, dfhack_exception_tostring);
lua_swap(L);
lua_pushvalue(L, 2);
if (lua_pcall(L, 2, 1, 0) != LUA_OK)
error_tostring(L);
}
else
error_tostring(L);
@ -652,7 +713,12 @@ static int dfhack_coauxwrap (lua_State *L) {
if (Lua::IsSuccess(r))
return lua_gettop(L);
else
{
if (lua_checkstack(L, LUA_MINSTACK))
convert_to_exception(L, 1);
return lua_error(L);
}
}
static int dfhack_cowrap (lua_State *L) {
@ -1159,6 +1225,7 @@ static const luaL_Reg dfhack_funcs[] = {
{ "safecall", dfhack_safecall },
{ "saferesume", dfhack_saferesume },
{ "onerror", dfhack_onerror },
{ "error", dfhack_error },
{ "call_with_finalizer", dfhack_call_with_finalizer },
{ "with_suspend", lua_dfhack_with_suspend },
{ "open_plugin", dfhack_open_plugin },
@ -1359,6 +1426,8 @@ lua_State *DFHack::Lua::Open(color_ostream &out, lua_State *state)
lua_newtable(state);
lua_pushcfunction(state, dfhack_exception_tostring);
lua_setfield(state, -2, "__tostring");
lua_pushcfunction(state, dfhack_exception_tostring);
lua_setfield(state, -2, "tostring");
lua_dup(state);
lua_rawsetp(state, LUA_REGISTRYINDEX, &DFHACK_EXCEPTION_META_TOKEN);
lua_setfield(state, -2, "exception");

@ -111,6 +111,8 @@ namespace DFHack
void printerr(const char *format, ...);
void vprinterr(const char *format, va_list args);
/// Get color
color_value color() { return cur_color; }
/// Set color (ANSI color number)
void color(color_value c);
/// Reset color to default

@ -49,6 +49,10 @@ function dfhack.pcall(f, ...)
return xpcall(f, dfhack.onerror, ...)
end
function qerror(msg, level)
dfhack.error(msg, (level or 1) + 1, false)
end
function dfhack.with_finalize(...)
return dfhack.call_with_finalizer(0,true,...)
end

@ -154,7 +154,8 @@ function MemoryArea.new(astart, aend)
int16_t = CheckedArray.new('int16_t',astart,aend),
uint16_t = CheckedArray.new('uint16_t',astart,aend),
int32_t = CheckedArray.new('int32_t',astart,aend),
uint32_t = CheckedArray.new('uint32_t',astart,aend)
uint32_t = CheckedArray.new('uint32_t',astart,aend),
float = CheckedArray.new('float',astart,aend)
}
setmetatable(obj, MemoryArea)
return obj
@ -168,7 +169,7 @@ function MemoryArea:__tostring()
return string.format('<MemoryArea: %x..%x>', self.start_addr, self.end_addr)
end
function MemoryArea:contains_range(start,size)
return start >= self.start_addr and (start+size) <= self.end_addr
return size >= 0 and start >= self.start_addr and (start+size) <= self.end_addr
end
function MemoryArea:contains_obj(obj,count)
local size, base = df.sizeof(obj)
@ -234,7 +235,7 @@ function found_offset(name,val)
if not val then
print('Could not find offset '..name)
if not cval and not utils.prompt_yes_no('Continue with the script?') then
error('User quit')
qerror('User quit')
end
return
end
@ -251,6 +252,16 @@ function found_offset(name,val)
end
else
dfhack.internal.setAddress(name, val)
local ival = val - dfhack.internal.getRebaseDelta()
local entry = string.format("<global-address name='%s' value='0x%x'/>\n", name, ival)
local ccolor = dfhack.color(COLOR_LIGHTGREEN)
dfhack.print(entry)
dfhack.color(ccolor)
io.stdout:write(entry)
io.stdout:flush()
end
end
@ -453,4 +464,30 @@ function DiffSearcher:find_counter(prompt,data_type,delta,action_prompt)
)
end
-- Screen size
function get_screen_size()
-- Use already known globals
if dfhack.internal.getAddress('init') then
local d = df.global.init.display
return d.grid_x, d.grid_y
end
if dfhack.internal.getAddress('gps') then
local g = df.global.gps
return g.dimx, g.dimy
end
-- Parse stdout.log for resize notifications
io.stdout:flush()
local w,h = 80,25
for line in io.lines('stdout.log') do
local cw, ch = string.match(line, '^Resizing grid to (%d+)x(%d+)$')
if cw and ch then
w, h = tonumber(cw), tonumber(ch)
end
end
return w,h
end
return _ENV

@ -379,7 +379,7 @@ function prompt_yes_no(msg,default)
elseif string.match(rv,'^[Nn]') then
return false
elseif rv == 'abort' then
error('User abort in utils.prompt_yes_no()')
qerror('User abort in utils.prompt_yes_no()')
elseif rv == '' and default ~= nil then
return default
end

@ -5,6 +5,8 @@ local ms = require 'memscan'
local is_known = dfhack.internal.getAddress
local os_type = dfhack.getOSType()
local force_scan = {}
for _,v in ipairs({...}) do
force_scan[v] = true
@ -22,7 +24,10 @@ PERMANENT SAVE CORRUPTION.
Finding the first few globals requires this script to be
started immediately after loading the game, WITHOUT
first loading a world.
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
@ -38,12 +43,12 @@ end
local data = ms.get_data_segment()
if not data then
error('Could not find data segment')
qerror('Could not find data segment')
end
print('\nData section: '..tostring(data))
if data.size < 5000000 then
error('Data segment too short.')
qerror('Data segment too short.')
end
local searcher = ms.DiffSearcher.new(data)
@ -56,6 +61,34 @@ local function validate_offset(name,validator,addr,tname,...)
ms.found_offset(name,obj)
end
local function zoomed_searcher(startn, end_or_sz)
if force_scan.nozoom then
return nil
end
local sv = is_known(startn)
if not sv then
return nil
end
local ev
if type(end_or_sz) == 'number' then
ev = sv + end_or_sz
if end_or_sz < 0 then
sv, ev = ev, sv
end
else
ev = is_known(end_or_sz)
if not ev then
return nil
end
end
sv = sv - (sv % 4)
ev = ev + 3
ev = ev - (ev % 4)
if data:contains_range(sv, ev-sv) then
return ms.DiffSearcher.new(ms.MemoryArea.new(sv,ev))
end
end
local function exec_finder(finder, names)
if type(names) ~= 'table' then
names = { names }
@ -70,7 +103,7 @@ local function exec_finder(finder, names)
if not dfhack.safecall(finder) then
if not utils.prompt_yes_no('Proceed with the rest of the script?') then
searcher:reset()
error('Quit')
qerror('Quit')
end
end
else
@ -80,7 +113,8 @@ end
local ordinal_names = {
[0] = '1st entry',
[1] = '2nd entry'
[1] = '2nd entry',
[2] = '3rd entry'
}
setmetatable(ordinal_names, {
__index = function(self,idx) return (idx+1)..'th entry' end
@ -218,6 +252,83 @@ local function find_gview()
dfhack.printerr('Could not find gview')
end
--
-- enabler
--
local function is_valid_enabler(e)
if not ms.is_valid_vector(e.textures.raws, 4)
or not ms.is_valid_vector(e.text_system, 4)
then
dfhack.printerr('Vector layout check failed.')
return false
end
return true
end
local function find_enabler()
-- Data from data/init/colors.txt
local colors = {
0, 0, 0, 0, 0, 128, 0, 128, 0,
0, 128, 128, 128, 0, 0, 128, 0, 128,
128, 128, 0, 192, 192, 192, 128, 128, 128,
0, 0, 255, 0, 255, 0, 0, 255, 255,
255, 0, 0, 255, 0, 255, 255, 255, 0,
255, 255, 255
}
for i = 1,#colors do colors[i] = colors[i]/255 end
local idx, addr = data.float:find_one(colors)
if idx then
validate_offset('enabler', is_valid_enabler, addr, df.enabler, 'ccolor')
return
end
dfhack.printerr('Could not find enabler')
end
--
-- gps
--
local function is_valid_gps(g)
if g.clipx[0] < 0 or g.clipx[0] > g.clipx[1] or g.clipx[1] >= g.dimx then
dfhack.printerr('Invalid clipx: ', g.clipx[0], g.clipx[1], g.dimx)
end
if g.clipy[0] < 0 or g.clipy[0] > g.clipy[1] or g.clipy[1] >= g.dimy then
dfhack.printerr('Invalid clipy: ', g.clipy[0], g.clipy[1], g.dimy)
end
return true
end
local function find_gps()
print('\nPlease ensure the mouse cursor is not over the game window.')
if not utils.prompt_yes_no('Proceed?', true) then
return
end
local zone
if os_type == 'windows' or os_type == 'linux' then
zone = zoomed_searcher('cursor', 0x1000)
elseif os_type == 'darwin' then
zone = zoomed_searcher('enabler', 0x1000)
end
zone = zone or searcher
local w,h = ms.get_screen_size()
local idx, addr = zone.area.int32_t:find_one{w, h, -1, -1}
if idx then
validate_offset('gps', is_valid_gps, addr, df.graphic, 'dimx')
return
end
dfhack.printerr('Could not find gps')
end
--
-- World
--
@ -356,6 +467,88 @@ number, so when it shows "Min (5000df", it means 50000:]],
addr, df.ui_build_selector, 'plate_info', 'unit_min')
end
--
-- init
--
local function is_valid_init(i)
-- derived from curses_*.png image sizes presumably
if i.font.small_font_dispx ~= 8 or i.font.small_font_dispy ~= 12 or
i.font.large_font_dispx ~= 10 or i.font.large_font_dispy ~= 12 then
print('Unexpected font sizes: ',
i.font.small_font_dispx, i.font.small_font_dispy,
i.font.large_font_dispx, i.font.large_font_dispy)
if not utils.prompt_yes_no('Ignore?') then
return false
end
end
return true
end
local function find_init()
local zone
if os_type == 'windows' then
zone = zoomed_searcher('ui_build_selector', 0x3000)
elseif os_type == 'linux' or os_type == 'darwin' then
zone = zoomed_searcher('d_init', -0x2000)
end
zone = zone or searcher
local idx, addr = zone.area.int32_t:find_one{250, 150, 15, 0}
if idx then
validate_offset('init', is_valid_init, addr, df.init, 'input', 'hold_time')
return
end
local w,h = ms.get_screen_size()
local idx, addr = zone.area.int32_t:find_one{w, h}
if idx then
validate_offset('init', is_valid_init, addr, df.init, 'display', 'grid_x')
return
end
dfhack.printerr('Could not find init')
end
--
-- current_weather
--
local function find_current_weather()
print('\nPlease load the save previously processed with prepare-save.')
if not utils.prompt_yes_no('Proceed?', true) then
return
end
local zone
if os_type == 'windows' then
zone = zoomed_searcher('crime_next_id', 512)
elseif os_type == 'darwin' then
zone = zoomed_searcher('cursor', -64)
elseif os_type == 'linux' then
zone = zoomed_searcher('ui_building_assign_type', -512)
end
zone = zone or searcher
local wbytes = {
2, 1, 0, 2, 0,
1, 2, 1, 0, 0,
2, 0, 2, 1, 2,
1, 2, 0, 1, 1,
2, 0, 1, 0, 2
}
local idx, addr = zone.area.int8_t:find_one(wbytes)
if idx then
ms.found_offset('current_weather', addr)
return
end
dfhack.printerr('Could not find current_weather - must be a wrong save.')
end
--
-- ui_menu_width
--
@ -578,6 +771,124 @@ NOTE: If not done after first 3-4 steps, resize the game window.]],
ms.found_offset('window_z', addr)
end
--
-- cur_year
--
local function find_cur_year()
local zone
if os_type == 'windows' then
zone = zoomed_searcher('formation_next_id', 32)
elseif os_type == 'darwin' then
zone = zoomed_searcher('cursor', -32)
elseif os_type == 'linux' then
zone = zoomed_searcher('ui_building_assign_type', -512)
end
if not zone then
dfhack.printerr('Cannot search for cur_year - prerequisites missing.')
return
end
local yvalue = utils.prompt_input('Please enter current in-game year: ', utils.check_number)
local idx, addr = zone.area.int32_t:find_one{yvalue}
if idx then
ms.found_offset('cur_year', addr)
return
end
dfhack.printerr('Could not find cur_year')
end
--
-- cur_year_tick
--
local function find_cur_year_tick()
local zone
if os_type == 'windows' then
zone = zoomed_searcher('artifact_next_id', -32)
else
zone = zoomed_searcher('cur_year', 128)
end
if not zone then
dfhack.printerr('Cannot search for cur_year_tick - prerequisites missing.')
return
end
local addr = zone:find_counter([[
Searching for cur_year_tick. Please exit to main dwarfmode
menu, then do as instructed below:]],
'int32_t', 1,
"Please press '.' to step the game one frame."
)
ms.found_offset('cur_year_tick', addr)
end
--
-- process_jobs
--
local function get_process_zone()
if os_type == 'windows' then
return zoomed_searcher('ui_workshop_job_cursor', 'ui_building_in_resize')
elseif os_type == 'linux' or os_type == 'darwin' then
return zoomed_searcher('cur_year', 'cur_year_tick')
end
end
local function find_process_jobs()
local zone = get_process_zone() or searcher
local addr = zone:find_menu_cursor([[
Searching for process_jobs. Please do as instructed below:]],
'int8_t',
{ 1, 0 },
{ [1] = 'designate a building to be constructed, e.g a bed',
[0] = 'step or unpause the game to reset the flag' }
)
ms.found_offset('process_jobs', addr)
end
--
-- process_dig
--
local function find_process_dig()
local zone = get_process_zone() or searcher
local addr = zone:find_menu_cursor([[
Searching for process_dig. Please do as instructed below:]],
'int8_t',
{ 1, 0 },
{ [1] = 'designate a tile to be mined out',
[0] = 'step or unpause the game to reset the flag' }
)
ms.found_offset('process_dig', addr)
end
--
-- pause_state
--
local function find_pause_state()
local zone
if os_type == 'linux' or os_type == 'darwin' then
zone = zoomed_searcher('ui_look_cursor', 32)
elseif os_type == 'windows' then
zone = zoomed_searcher('ui_workshop_job_cursor', 80)
end
zone = zone or searcher
local addr = zone:find_menu_cursor([[
Searching for pause_state. Please do as instructed below:]],
'int8_t',
{ 1, 0 },
{ [1] = 'PAUSE the game',
[0] = 'UNPAUSE the game' }
)
ms.found_offset('pause_state', addr)
end
--
-- MAIN FLOW
--
@ -588,6 +899,8 @@ exec_finder(find_cursor, { 'cursor', 'selection_rect', 'gamemode', 'gametype' })
exec_finder(find_announcements, 'announcements')
exec_finder(find_d_init, 'd_init')
exec_finder(find_gview, 'gview')
exec_finder(find_enabler, 'enabler')
exec_finder(find_gps, 'gps')
print('\nCompound globals (need loaded world):\n')
@ -595,9 +908,11 @@ exec_finder(find_world, 'world')
exec_finder(find_ui, 'ui')
exec_finder(find_ui_sidebar_menus, 'ui_sidebar_menus')
exec_finder(find_ui_build_selector, 'ui_build_selector')
exec_finder(find_init, 'init')
print('\nPrimitive globals:\n')
exec_finder(find_current_weather, 'current_weather')
exec_finder(find_ui_menu_width, { 'ui_menu_width', 'ui_area_map_width' })
exec_finder(find_ui_selected_unit, 'ui_selected_unit')
exec_finder(find_ui_unit_view_mode, 'ui_unit_view_mode')
@ -611,5 +926,13 @@ exec_finder(find_window_x, 'window_x')
exec_finder(find_window_y, 'window_y')
exec_finder(find_window_z, 'window_z')
print('\nUnpausing globals:\n')
exec_finder(find_cur_year, 'cur_year')
exec_finder(find_cur_year_tick, 'cur_year_tick')
exec_finder(find_process_jobs, 'process_jobs')
exec_finder(find_process_dig, 'process_dig')
exec_finder(find_pause_state, 'pause_state')
print('\nDone. Now add newly-found globals to symbols.xml.')
searcher:reset()

@ -0,0 +1,71 @@
-- Prepare the current save for use with devel/find-offsets.
df.global.pause_state = true
--[[print('Placing anchor...')
do
local wp = df.global.ui.waypoints
for _,pt in ipairs(wp.points) do
if pt.name == 'dfhack_anchor' then
print('Already placed.')
goto found
end
end
local x,y,z = pos2xyz(df.global.cursor)
if not x then
error("Place cursor at your preferred anchor point.")
end
local id = wp.next_point_id
wp.next_point_id = id + 1
wp.points:insert('#',{
new = true, id = id, name = 'dfhack_anchor',
comment=(x..','..y..','..z),
tile = string.byte('!'), fg_color = COLOR_LIGHTRED, bg_color = COLOR_BLUE,
pos = xyz2pos(x,y,z)
})
::found::
end]]
print('Nicknaming units...')
for i,unit in ipairs(df.global.world.units.active) do
dfhack.units.setNickname(unit, i..':'..unit.id)
end
print('Setting weather...')
local wbytes = {
2, 1, 0, 2, 0,
1, 2, 1, 0, 0,
2, 0, 2, 1, 2,
1, 2, 0, 1, 1,
2, 0, 1, 0, 2
}
for i=0,4 do
for j = 0,4 do
df.global.current_weather[i][j] = (wbytes[i*5+j+1] or 2)
end
end
local yearstr = df.global.cur_year..','..df.global.cur_year_tick
print('Cur year and tick: '..yearstr)
dfhack.persistent.save{
key='prepare-save/cur_year',
value=yearstr,
ints={df.global.cur_year, df.global.cur_year_tick}
}
-- Save
dfhack.run_script('quicksave')

@ -116,8 +116,7 @@ if opt then
if opt == '--fix' then
fix = true
else
dfhack.printerr('Invalid option: '..opt)
return
qerror('Invalid option: '..opt)
end
end

@ -1,8 +1,7 @@
-- Makes the game immediately save the state.
if not dfhack.isMapLoaded() then
dfhack.printerr("World and map aren't loaded.")
return
qerror("World and map aren't loaded.")
end
local ui_main = df.global.ui.main