@ -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 & 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 & 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,
@ -753,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.
@ -782,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
@ -801,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 >
< h 3 > < a class = "toc-backref" href = "#id1 5 "> Persistent configuration storage< / a > < / h 3 >
< 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
@ -838,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" >
< h 2 > < a class = "toc-backref" href = "#id1 2 "> Material info lookup< / a > < / h 2 >
< h 3 > < a class = "toc-backref" href = "#id1 6 "> Material info lookup< / a > < / h 3 >
< 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 >
@ -881,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 = "#id1 3 "> C++ function wrappers< / a > < / h2 >
< h2 > < a class = "toc-backref" href = "#id1 7 "> 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
@ -911,7 +969,7 @@ can be omitted.</p>
< / li >
< / ul >
< div class = "section" id = "gui-module" >
< h3 > < a class = "toc-backref" href = "#id1 4 "> Gui module< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id1 8 "> 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 >
@ -947,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 = "#id1 5 "> Job module< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id1 9 "> 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 >
@ -984,7 +1042,7 @@ a lua list containing them.</p>
< / ul >
< / div >
< div class = "section" id = "units-module" >
< h3 > < a class = "toc-backref" href = "#id 16 "> Units module< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id 20 "> 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 >
@ -1038,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 = "#id 17 "> Items module< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id 2 1"> 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 >
@ -1081,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 = "#id 18 "> Maps module< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id 22 "> 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 >
@ -1122,7 +1180,7 @@ burrows, or the presence of invaders.</p>
< / ul >
< / div >
< div class = "section" id = "burrows-module" >
< h3 > < a class = "toc-backref" href = "#id 19 "> Burrows module< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id 23 "> 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 >
@ -1157,7 +1215,7 @@ burrows, or the presence of invaders.</p>
< / ul >
< / div >
< div class = "section" id = "buildings-module" >
< h3 > < a class = "toc-backref" href = "#id2 0 "> Buildings module< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id2 4 "> 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 >
@ -1297,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 = "#id2 1 "> Constructions module< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id2 5 "> 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
@ -1313,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 = "#id2 2 "> Internal API< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id2 6 "> Internal API< / a > < / h3 >
< p > These functions are intended for the use by dfhack developers,
and are only documented here for completeness:< / p >
< ul >
@ -1356,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 = "#id2 3 "> Core interpreter context< / a > < / h2 >
< h2 > < a class = "toc-backref" href = "#id2 7 "> 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 >
@ -1387,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 = "#id2 4 "> Event type< / a > < / h3 >
< h3 > < a class = "toc-backref" href = "#id2 8 "> 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.
@ -1413,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 = "#id2 5 "> Plugins< / a > < / h1 >
< h1 > < a class = "toc-backref" href = "#id2 9 "> 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.< name> ')< / 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 = "#id 26 "> burrows< / a > < / h2 >
< h2 > < a class = "toc-backref" href = "#id 30 "> burrows< / a > < / h2 >
< p > Implements extended burrow manipulations.< / p >
< p > Events:< / p >
< ul >
@ -1458,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 = "#id 27 "> sort< / a > < / h2 >
< h2 > < a class = "toc-backref" href = "#id 31 "> 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 >
Alexander Gavrilov